feat: Implement manpage generation

Author: pawamoy

README.md

@@ -8,6 +8,10 @@
 
 MkDocs plugin to generate a manpage from the documentation site.
 
+## Requirements
+
+Pandoc must be [installed](https://pandoc.org/installing.html) and available as `pandoc`.
+
 ## Installation
 
 With `pip`:
@@ -20,3 +24,48 @@ With [`pipx`](https://github.com/pipxproject/pipx):
 python3.7 -m pip install --user pipx
 pipx install mkdocs-manpage
 ```
+
+## Usage
+
+```yaml
+# mkdocs.yml
+plugins:
+- manpage:
+    enabled: !ENV [MANPAGE, false]
+    pages:
+    - index.md
+    - usage.md
+    - reference/api.md
+```
+
+We also recommend disabling some options from other plugins/extensions
+to improve the final manual page:
+
+- no source code through `mkdocstrings`:
+
+    ```yaml
+    - mkdocstrings:
+        handlers:
+          python:
+            options:
+              show_source: !ENV [SHOW_SOURCE, true]
+    ```
+
+- no permalink through `toc`:
+
+    ```yaml
+    markdown_extensions:
+    - toc:
+        permalink: !ENV [PERMALINK, true]
+    ```
+
+Then set these environment variables before building
+the documentation and generating the manpage:
+
+```bash
+export MANPAGE=true
+export PERMALINK=false
+export SHOW_SOURCE=false
+mkdocs build
+# manpage is in site dir: ./site/manpage.1
+```

docs/insiders/changelog.md

@@ -2,6 +2,6 @@
 
 ## MkDocs Manpage Insiders
 
-### 1.0.0 <small>April 22, 2023</small> { id="1.0.0" }
+### 1.0.0 <small>June 06, 2023</small> { id="1.0.0" }
 
 - Release first Insiders version

docs/insiders/goals.yml

@@ -1 +1,7 @@
-goals: {}
+goals:
+  500:
+    name: PlasmaVac User Guide
+    features:
+    - name: The project itself!
+      ref: /
+      since: 2023/06/06

duties.py

@@ -300,3 +300,18 @@ def test(ctx: Context, match: str = "") -> None:
         pytest.run("-n", "auto", "tests", config_file="config/pytest.ini", select=match),
         title=pyprefix("Running tests"),
     )
+
+
+@duty(aliases=["man"])
+def manpage(ctx: Context) -> None:
+    """Run the test suite.
+
+    Parameters:
+        ctx: The context instance (passed automatically).
+    """
+    os.environ["MANPAGE"] = "true"
+    os.environ["SHOW_SOURCE"] = "false"
+    os.environ["PERMALINK"] = "false"
+    os.environ["DEPLOY"] = "false"
+    ctx.run(mkdocs.build(), title="Building docs and manpage")
+    ctx.run("man ./site/manpage.1", capture=False)

mkdocs.yml

@@ -92,7 +92,7 @@ markdown_extensions:
 - pymdownx.tasklist:
     custom_checkbox: true
 - toc:
-    permalink: "¤"
+    permalink: !ENV [PERMALINK, "¤"]
 
 plugins:
 - search
@@ -113,10 +113,22 @@ plugins:
           merge_init_into_class: true
           docstring_options:
             ignore_init_summary: true
+          show_source: !ENV [SHOW_SOURCE, true]
 - git-committers:
     enabled: !ENV [DEPLOY, false]
     repository: pawamoy/mkdocs-manpage
-
+- manpage:
+    enabled: !ENV [MANPAGE, false]
+    pages:
+    - index.md
+    - changelog.md
+    - credits.md
+    - license.md
+    - contributing.md
+    - code_of_conduct.md
+    - insiders/index.md
+    - insiders/installation.md
+    - insiders/changelog.md
 - minify:
     minify_html: !ENV [DEPLOY, false]
 

pyproject.toml

@@ -39,6 +39,9 @@ Discussions = "https://github.com/pawamoy/mkdocs-manpage/discussions"
 Gitter = "https://gitter.im/mkdocs-manpage/community"
 Funding = "https://github.com/sponsors/pawamoy"
 
+[project.entry-points."mkdocs.plugins"]
+manpage = "mkdocs_manpage.plugin:MkdocsManpagePlugin"
+
 [tool.pdm]
 version = {source = "scm"}
 plugins = [

src/mkdocs_manpage/config.py

@@ -0,0 +1,70 @@
+"""Configuration options for the MkDocs Manpage plugin."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Dict, Generic, TypeVar
+
+from mkdocs.config import config_options as mkconf
+from mkdocs.config.base import Config
+from mkdocs.config.base import Config as BaseConfig
+from mkdocs.config.config_options import BaseConfigOption, LegacyConfig, ValidationError
+
+T = TypeVar("T")
+
+
+# TODO: remove once https://github.com/mkdocs/mkdocs/pull/3242 is merged and released
+class DictOfItems(Generic[T], BaseConfigOption[Dict[str, T]]):
+    """Validates a dict of items. Keys are always strings.
+
+    E.g. for `config_options.DictOfItems(config_options.Type(int))` a valid item is `{"a": 1, "b": 2}`.
+    """
+
+    required: bool | None = None  # Only for subclasses to set.
+
+    def __init__(self, option_type: BaseConfigOption[T], default: Any = None) -> None:  # noqa: D107
+        super().__init__()
+        self.default = default
+        self.option_type = option_type
+        self.option_type.warnings = self.warnings
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}: {self.option_type}"
+
+    def pre_validation(self, config: Config, key_name: str) -> None:  # noqa: D102
+        self._config = config
+        self._key_name = key_name
+
+    def run_validation(self, value: object) -> dict[str, T]:  # noqa: D102
+        if value is None:
+            if self.required or self.default is None:
+                raise ValidationError("Required configuration not provided.")
+            value = self.default
+        if not isinstance(value, dict):
+            raise ValidationError(f"Expected a dict of items, but a {type(value)} was given.")
+        if not value:  # Optimization for empty list
+            return value
+
+        fake_config = LegacyConfig(())
+        with contextlib.suppress(AttributeError):
+            fake_config.config_file_path = self._config.config_file_path
+
+        # Emulate a config-like environment for pre_validation and post_validation.
+        fake_config.data = value
+
+        for key_name in fake_config:
+            self.option_type.pre_validation(fake_config, key_name)
+        for key_name in fake_config:
+            # Specifically not running `validate` to avoid the OptionallyRequired effect.
+            fake_config[key_name] = self.option_type.run_validation(fake_config[key_name])
+        for key_name in fake_config:
+            self.option_type.post_validation(fake_config, key_name)
+
+        return value
+
+
+class PluginConfig(BaseConfig):
+    """Configuration options for the plugin."""
+
+    enabled = mkconf.Type(bool, default=True)
+    pages = mkconf.ListOfItems(mkconf.Type(str))

src/mkdocs_manpage/logger.py

@@ -0,0 +1,46 @@
+"""Logging functions."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, MutableMapping
+
+
+class PluginLogger(logging.LoggerAdapter):
+    """A logger adapter to prefix messages with the originating package name."""
+
+    def __init__(self, prefix: str, logger: logging.Logger):
+        """Initialize the object.
+
+        Arguments:
+            prefix: The string to insert in front of every message.
+            logger: The logger instance.
+        """
+        super().__init__(logger, {})
+        self.prefix = prefix
+
+    def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
+        """Process the message.
+
+        Arguments:
+            msg: The message:
+            kwargs: Remaining arguments.
+
+        Returns:
+            The processed message.
+        """
+        return f"{self.prefix}: {msg}", kwargs
+
+
+def get_logger(name: str) -> PluginLogger:
+    """Return a logger for plugins.
+
+    Arguments:
+        name: The name to use with `logging.getLogger`.
+
+    Returns:
+        A logger configured to work well in MkDocs,
+            prefixing each message with the plugin package name.
+    """
+    logger = logging.getLogger(f"mkdocs.plugins.{name}")
+    return PluginLogger(name.split(".", 1)[0], logger)

src/mkdocs_manpage/plugin.py

@@ -0,0 +1,103 @@
+"""MkDocs plugin that generates a manpage at the end of the build."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from shutil import which
+from typing import TYPE_CHECKING
+
+from mkdocs.plugins import BasePlugin
+
+from mkdocs_manpage.config import PluginConfig
+from mkdocs_manpage.logger import get_logger
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.pages import Page
+
+
+logger = get_logger(__name__)
+
+
+def _log_pandoc_output(output: str) -> None:
+    for line in output.split("\n"):
+        if line.startswith("[INFO]"):
+            logger.debug(f"pandoc: {line[7:]}")
+        elif line.startswith("[WARNING]"):
+            logger.warning(f"pandoc: {line[10:]}")
+        else:
+            logger.debug(f"pandoc: {line[8:]}")
+
+
+class MkdocsManpagePlugin(BasePlugin[PluginConfig]):
+    """The MkDocs plugin to generate manpages.
+
+    This plugin defines the following event hooks:
+
+    - `on_page_content`
+    - `on_post_build`
+
+    Check the [Developing Plugins](https://www.mkdocs.org/user-guide/plugins/#developing-plugins) page of `mkdocs`
+    for more information about its plugin system.
+    """
+
+    def __init__(self) -> None:  # noqa: D107
+        self.pages: dict[str, str] = {}
+
+    def on_page_content(self, html: str, *, page: Page, **kwargs: Any) -> str | None:  # noqa: ARG002
+        """Record pages contents.
+
+        Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).
+        In this hook we simply record the HTML of the pages into a dictionary whose keys are the pages' URIs.
+
+        Parameters:
+            html: The page HTML.
+            page: The page object.
+        """
+        if not self.config.enabled:
+            return None
+        if page.file.src_uri in self.config.pages or not self.config.pages:
+            logger.debug(f"Adding page {page.file.src_uri} to manpage")
+            self.pages[page.file.src_uri] = html
+        return html
+
+    def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG002
+        """Combine all recorded pages contents and convert it to a manual page with Pandoc.
+
+        Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
+        In this hook we concatenate all previously recorded HTML, and convert it to a manual page with Pandoc.
+
+        Parameters:
+            config: MkDocs configuration.
+        """
+        if not self.config.enabled:
+            return
+        pandoc = which("pandoc")
+        if pandoc is None:
+            logger.debug("Could not find pandoc executable, trying to call 'pandoc' directly")
+            pandoc = "pandoc"
+        pages = []
+        if self.config.pages:
+            for page in self.config.pages:
+                try:
+                    pages.append(self.pages[page])
+                except KeyError:
+                    logger.error(f"No page with path {page}")  # noqa: TRY400
+        else:
+            pages = list(self.pages.values())
+        combined = "\n\n".join(pages)
+        output_file = os.path.join(config.site_dir, "manpage.1")
+        with tempfile.NamedTemporaryFile("w", prefix="mkdocs_manpage_", suffix=".html") as temp_file:
+            temp_file.write(combined)
+            pandoc_process = subprocess.run(
+                [pandoc, "--verbose", "--standalone", "--to", "man", temp_file.name, "-o", output_file],  # noqa: S603
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+            )
+        _log_pandoc_output(pandoc_process.stdout)
+        logger.info(f"Generated manpage at {output_file}")

tests/test_plugin.py

@@ -0,0 +1,14 @@
+"""Tests for the plugin."""
+
+import os
+
+import pytest
+from duty.callables import mkdocs
+
+
+def test_plugin() -> None:
+    """Run the plugin."""
+    os.environ["MANPAGE"] = "true"
+    with pytest.raises(expected_exception=SystemExit) as exc:
+        mkdocs.build()()
+    assert exc.value.code == 0