Install & Compatibility
Where this runs
tested against v4.8.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 36.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 42MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pydoc_markdown
✓ Via command-line: pydoc-markdown
Pydoc-Markdown is primarily used via its command-line interface. Direct programmatic imports for generation are less common for end-users, focusing instead on configuration files.
This quickstart demonstrates how to generate Markdown API documentation for a simple Python module. It involves creating a Python file, defining a `pydoc-markdown.yml` configuration to specify the module and output, and then running the `pydoc-markdown` CLI command. The output is redirected to `API.md`.
mkdir my_project
cd my_project
# Create a sample Python module
cat << EOF > my_module.py
"""A simple example module."""
def greet(name: str) -> str:
"""Greets a person by name.
:param name: The name of the person to greet.
:returns: A greeting string.
"""
return f"Hello, {name}!"
class MyClass:
"""A sample class.
:ivar value: An example instance variable.
"""
def __init__(self, value: int):
self.value = value
def get_value(self) -> int:
"""Returns the stored value."""
return self.value
EOF
# Create a pydoc-markdown.yml configuration file
cat << EOF > pydoc-markdown.yml
loaders:
- type: python
search_path: [.]
renderer:
type: markdown
pages:
- title: My API
contents:
- 'my_module'
EOF
# Generate the documentation
pydoc-markdown --config pydoc-markdown.yml > API.md
# To view the generated Markdown (optional)
# cat API.md
pydoc-markdown --version
Debug
Known issues
gotchaThe project maintainer recommends considering `mkdocstrings` for new projects due to limited time for proper maintenance and development, despite continued updates.fixEvaluate `mkdocstrings` as an alternative, especially for new projects or if long-term active development and extensive community support are critical.
affects: All versions
breakingPython 3.7 compatibility was dropped in a recent version.fixEnsure your project uses Python 3.8 or newer when installing and running Pydoc-Markdown.
affects: 4.8.2 and newer
deprecatedThe 'old style' YAML/PyProject configuration was deprecated in versions around 4.6.0 in favor of Novella integration, but was then 'undeprecated' in 4.7.0 due to user preference.fixIf using versions between 4.6.0 and 4.7.0, consider migrating to Novella or upgrading to 4.7.0+ to safely use YAML configuration. For 4.7.0 and later, YAML configuration is fully supported again.
affects: 4.6.0 (deprecated), 4.7.0+ (undeprecated)
gotchaCompatibility issues with `databind` versions can lead to `ForwardRef` errors or `NoMatchingConverter` errors during configuration parsing.fixUpgrade Pydoc-Markdown to its latest version, which often includes updates to `databind` dependencies to fix such issues. For example, 4.8.1 upgraded to `^4.4.0` to fix a `ForwardRef` error.
affects: Specific versions, notably when `databind` is >=4.5
Upgrade
Version history
4.8.2latest on PyPI · released Jun 26, 2023
Audit
Dependencies
docspecrequiredCore library for parsing Python API objects.
docstring-parserrequiredParses various docstring formats (Sphinx, Google, etc.).
pyyamlrequiredRequired for YAML configuration files.
databind.corerequiredUsed for configuration (known to cause compatibility issues with older versions).