Skip to main content

MkDocs plugin to generate a manpage from the documentation site.

Project description

MkDocs Manpage

ci documentation pypi version gitpod gitter

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:
    - index.md
    - usage.md
    - reference/api.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

The manpage will be written into the root of the site directory and named manpage.1.

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) -> 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_manpage-1.0.0.tar.gz (9.1 kB view hashes)

Uploaded Source

Built Distribution

mkdocs_manpage-1.0.0-py3-none-any.whl (9.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page