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


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-2.0.0.tar.gz (9.6 kB view details)

Uploaded Source

Built Distribution

mkdocs_manpage-2.0.0-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

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

Hashes for mkdocs_manpage-2.0.0.tar.gz
Algorithm Hash digest
SHA256 bb89858f2e2c2ca5dee9ba2af68bfe46d87108a64be823b8238cb60c9e59771d
MD5 7a47b57a090d3c9facd5310dc3e94ee6
BLAKE2b-256 53efe9884d150309186df843ee3796c41b8c22ce71c05ee2c6d4eee342913238

See more details on using hashes here.

File details

Details for the file mkdocs_manpage-2.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_manpage-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 407fa6d99e6f6f00f8664a104b85886d6223106b14fcd19dd6f736cf5811a367
MD5 7324da879ac803786e9710ba2bf1bd79
BLAKE2b-256 e94e9157a453d64f4ee2d1660758d523ca217268d501e87f96cc88b7ec8de57f

See more details on using hashes here.

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