Create Python API documentation in Markdown format.
Project description
Pydoc-Markdown
Pydoc-Markdown is a tool to create Python API documentation in markdown format
based on lib2to3.
Features
- Parses the AST instead of running your code
- Understands multiple documentation styles (Sphinx, Google, Pydoc-Markdown)
- Resolves cross-references of the form
#PetType.CAT - Supports attribute docstrings (
#: ...before or string literals after the statement)
On the roadmap
- Mkdocs integration (for feature parity with Pydoc-Markdown 2.x)
- Support for images (#94)
- Understand fixmes and hints in the source code (eg.
# doc: ignore) - Cross-page (and cross-project) links in API documentation
Usage
Pydoc-Markdown 3 is not currently available on PyPI. To install the current development version, you can simply pass the Git repository URL to Pip. It is recommended to install Pydoc-Markdown in isolation with Pipx.
$ pipx install git+https://github.com/NiklasRosenstein/pydoc-markdown.git@develop
This makes the pydoc-markdown command available in your command-line.
On the CLI you specify either the name of a configuration file or provide a
YAML formatted configuration. If you do not specify any arguments, the default
configuration file is loaded (pydoc-markdown.ya?ml).
$ pydoc-markdown [<config>]
The configuration is composed of three main components: A list of loaders, a list of documentation processors and a renderer. The default configuration is defined as follows:
loaders:
- type: python
processors:
- type: filter
- type: smart
- type: crossref
renderer:
- type: markdown
It is automatically applied when using the Pydoc-Markdown CLI to render Markdown documentation for Python modules on the fly (without a YAML configuration file). Example:
$ cat <<EOF >a.py
def say_hello(name: str):
""" Says hello to the person specified with *name*.
:param name: The person to say hello to.
:raises ValueError: If *name* is empty.
:returns: Nothing """
# ...
EOF
$ pydoc-markdown -m a -I .
Expand to see the generated Markdown
a
say_hello
say_hello(name: str)
Says hello to the person specified with name.
Arguments:
name: The person to say hello to.
Raises:
ValueError: If name is empty.
Returns:
Nothing
To jumpstart your documentation endavours, try running pydoc-markdown --bootstrap or
pydoc-markdown --bootsrap-mkdocs to generate a template configuration file.
If a configuration file exists, then the CLI needs to be invoked without
arguments, or with one argument that specifies the path to the configuration
file. When using the mkdocs renderer, you may add the --watch-and-serve
and --open arguments for smooth live-feedback.
$ pydoc-markdown ./pydoc-markdown.yaml -wo
lib2to3 Quirks
Pydoc-Markdown doesn't execute your Python code but instead relies on the
lib2to3 parser. This means it also inherits any quirks of lib2to3.
List of known quirks
- A function argument in Python 3 cannot be called
printeven though it is legal syntax
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
