Python Source Docs

Use the optional python_docs plugin to turn Python modules into source-backed documentation pages.

The plugin only runs when it is explicitly listed in hooks and enabled in its config section.

Example

[markata-go]
hooks = ["default", "python_docs"]

[markata-go.python_docs]
enabled = true
patterns = ["src/**/*.py", "pkg/**/*.py"]
exclude = ["**/tests/**", "**/.venv/**"]
slug_prefix = "api"
template = "docs"
include_source = true
include_module_code = false
published = false

This creates one generated post per discovered Python module.

Examples:

pkg/util.py -> /api/pkg/util/
pkg/client/http.py -> /api/pkg/client/http/
pkg/__init__.py -> /api/pkg/

What Gets Rendered

For each module, the plugin generates markdown that includes:

the module name and source path
the module docstring rendered as markdown
an imports section
an API index for classes and functions
per-symbol sections with signatures and docstrings
collapsible source snippets without repeated leading docstrings

Cross-Linking

When multiple modules are documented together, the plugin links internal references where possible.

Supported cases include:

import lists like from pkg.util import greet
backticked references like `pkg.util`
Sphinx-style refs like :func:pkg.util.greet``

Common Options

[markata-go]
hooks = ["default", "python_docs"]

[markata-go.python_docs]
enabled = true
patterns = ["src/**/*.py"]
directories = ["pkg", "scripts"]
exclude = ["**/tests/**"]
use_gitignore = true
slug_prefix = "reference"
template = "docs"
published = false
include_private = false
include_source = true
include_module_code = false
tags = ["python", "docs"]
interpreter = "python3"

Notes

The plugin requires a Python interpreter on PATH.
The plugin must be listed in [markata-go].hooks as python_docs.
Markdown content loading is unchanged; Python docs are added alongside normal posts.
Generated docs are unpublished by default so they stay out of feeds and sitemap unless you opt in.