MkDocs plugin to generate a manpage from the documentation site.
Project description
MkDocs Manpage
MkDocs plugin to generate a manpage from the documentation site.
Requirements
Pandoc must be installed and available as pandoc
.
Installation
With pip
:
pip install mkdocs-manpage[preprocess]
With pipx
:
python3.8 -m pip install --user pipx
pipx install mkdocs-manpage[preprocess]
Usage
# mkdocs.yml
plugins:
- manpage:
pages:
- title: My Project # defaults to site name
output: share/man/man1/my-project.1
inputs:
- index.md
- usage.md
- title: my-project API
header: Python Library APIs # defaults to common header for section 3 (see `man man`)
output: share/man/man3/my_project.3
inputs:
- reference/my_project/*.md
To enable/disable the plugin with an environment variable:
# mkdocs.yml
plugins:
- manpage:
enabled: !ENV [MANPAGE, false]
Then set the environment variable and run MkDocs:
MANPAGE=true mkdocs build
Pre-processing HTML
This plugin works by concatenating the HTML from all selected pages into a single file that is then converted to a manual page using Pandoc.
With a complete conversion, the final manual page will not look so good. For example images and SVG will be rendered as long strings of data and/or URIs. So this plugin allows users to pre-process the HTML, to remove unwanted HTML elements before converting the whole thing to a manpage.
First, you must make sure to install the preprocess
extra:
pip install mkdocs-manpage[preprocess]
To pre-process the HTML, we use BeautifulSoup.
Users have to write their own preprocess
function in order to modify the soup
returned by BeautifulSoup:
from bs4 import BeautifulSoup, Tag
def to_remove(tag: Tag) -> bool:
# remove images and SVGs
if tag.name in {"img", "svg"}:
return True
# remove links containing images or SVGs
if tag.name == "a" and tag.img and to_remove(tag.img):
return True
# remove permalinks
if tag.name == "a" and "headerlink" in tag.get("class", ()):
return True
return False
def preprocess(soup: BeautifulSoup, output: str) -> None:
for element in soup.find_all(to_remove):
element.decompose()
Then, instruct the plugin to use this module and its preprocess
function:
plugins:
- manpage:
preprocess: scripts/preprocess.py
See the documentation of both [BeautifulSoup
][bs4.BeautifulSoup] and [Tag
][bs4.Tag]
to know what methods are available to correctly select the elements to remove.
The alternative to HTML processing for improving the final manpage is disabling some options from other plugins/extensions:
-
no source code through
mkdocstrings
:- mkdocstrings: handlers: python: options: show_source: !ENV [SHOW_SOURCE, true]
-
no permalink through
toc
:markdown_extensions: - toc: permalink: !ENV [PERMALINK, true]
Then set these environment variables before building the documentation and generating the manpage:
export MANPAGE=true
export PERMALINK=false
export SHOW_SOURCE=false
mkdocs build
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkdocs_manpage-2.0.0.tar.gz
.
File metadata
- Download URL: mkdocs_manpage-2.0.0.tar.gz
- Upload date:
- Size: 9.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.11.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bb89858f2e2c2ca5dee9ba2af68bfe46d87108a64be823b8238cb60c9e59771d |
|
MD5 | 7a47b57a090d3c9facd5310dc3e94ee6 |
|
BLAKE2b-256 | 53efe9884d150309186df843ee3796c41b8c22ce71c05ee2c6d4eee342913238 |
File details
Details for the file mkdocs_manpage-2.0.0-py3-none-any.whl
.
File metadata
- Download URL: mkdocs_manpage-2.0.0-py3-none-any.whl
- Upload date:
- Size: 9.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.11.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 407fa6d99e6f6f00f8664a104b85886d6223106b14fcd19dd6f736cf5811a367 |
|
MD5 | 7324da879ac803786e9710ba2bf1bd79 |
|
BLAKE2b-256 | e94e9157a453d64f4ee2d1660758d523ca217268d501e87f96cc88b7ec8de57f |