Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Create Python API documentation in Markdown format

Project description


– *insipired by the `Keras <>`__ Documentation*

Pydocmd uses `MkDocs <>`__ and extended
`Markdown <>`__ syntax to generate
beautiful Python API documentation.


- [x] Support ``+`` suffix to include documented members of a
- [ ] Expand and link cross-references (eg. ``#SomeClass``)
- [ ] Parse, format and link types listed in
parameter/member/raise/return type docstrings (eg.
``someattr (int): This is...``)



pip install pydoc-markdown
pip install git+ # latest development version


Pydocmd can generate plain Markdown files from Python modules using the
``pydocmd simple`` command. Specify one or more module names on the
command-line. Supports the ``+`` syntax to include members of the module
(or ``++`` to include members of the members, etc.)


pydocmd simple mypackage+ mypackage.mymodule+ >

Alternatively, pydocmd wraps the MkDocs command-line interface and
generates the markdown pages beforehand. Simply use ``pydocmd build`` to
build the documentation, or ``pydocmd serve`` to serve the documentation
on a local HTTP server. The ``pydocmd gh-deploy`` from MkDocs is also

A configuration file ``pydocmd.yml`` is required to use pydocmd in this
mode. Below is an example configuration. To get started, create
``docs/`` directory and a file ``pydocmd.yml`` inside of it. Copy the
configuration below and adjust it to your needs, then run
``pydocmd build`` from the ``docs/`` directory.

.. code:: yaml

site_name: "My Documentation"

# This tells pydocmd which pages to generate from which Python modules,
# functions and classes. At the first level is the page name, below that
# is a tree of Python member names (modules, classes, etc.) that should be
# documented. Higher indentation leads to smaller header size.
- baz/
- foobar.baz:
- foobar.baz.CoolClass+ # (+ to include members)
- foobar.baz.some_function
- baz/
- foobar.more++ # (++ to include members, and their members)

# MkDocs pages configuration. The `<<` operator is sugar added by pydocmd
# that allows you to use an external Markdown file (eg. your project's README)
# in the documentation. The path must be relative to current working directory.
- Home: << ../
- foobar.baz:
- Cool Stuff: baz/

# These options all show off their default values. You don't have to add
# them to your configuration if you're fine with the default.
docs_dir: sources
gens_dir: _build/pydocmd # This will end up as the MkDocs 'docs_dir'
site_dir: _build/site
theme: readthedocs
loader: pydocmd.loader.PythonLoader
preprocessor: pydocmd.preprocessor.Preprocessor

# Additional search path for your Python module. If you use Pydocmd from a
# subdirectory of your project (eg. docs/), you may want to add the parent
# directory here.
- ..



Symbols in the same namespace may be referenced by using a hash-symbol
(``#``) directly followed by the symbols' name, including relative
references. Note that using parentheses for function names is encouraged
and will be ignored and automatically added when converting docstrings.
Examples: ``#ClassName.member`` or ``#mod.function()``.

For absolute references for modules or members in names that are not
available in the current global namespace, ``#::mod.member`` must be
used (note the two preceeding two double-colons).

For long reference names where only some part of the name should be
displayed, the syntax ```` can be used, where
``X`` is the number of elements to keep. If ``X`` is omitted, it will be
assumed 1. Example: ```` results in only ``name``
being displayed.

In order to append additional characters that are not included in the
actual reference name, another hash-symbol can be used, like

**pydoc-markdown** can be extended to find other cross-references using
the `Extension
API <>`__.


Sections can be generated with the Markdown ``# <Title>`` syntax. It is
important to add a whitespace after the hash-symbol (``#``), as
otherwise it would represent a cross-reference. Some special sections
alter the rendered result of their content, including

- Arguments (1)
- Parameters (1)
- Attributes (1)
- Members (1)
- Raises (2)
- Returns (2)

(1): Lines beginning with ``<ident> [(<type>[, ...])]:`` are treated as
argument/parameter or attribute/member declarations. Types listed inside
the parenthesis (optional) are cross-linked, if possible. For
attribute/member declarations, the identifier is typed in a monospace

(2): Lines beginning with ``<type>[, ...]:`` are treated as raise/return
type declarations and the type names are cross-linked, if possible.

Lines following a name's description are considered part of the most
recent documentation unless separated by another declaration or an empty
line. ``<type>`` placeholders can also be tuples in the form
``(<type>[, ...])``.

Code Blocks

GitHub-style Markdown code-blocks with language annotations can be used.


>>> for i in range(100):



v2.0.2 (tip)

- Fix #25 -- Text is incorrectly rendered as code
- Fix #26 -- Broken links for URLs with fragment identifiers
- No longer transforms titles in a docstring that are indented (eg. to
avoid an indented code block with a ``#`` comment to be corrupted)


- Support ``additional_search_path`` key in configuration
- Render headers as HTML ``<hX>`` tags rather than Markdown tags, so we
assign a proper ID to them
- Fix #21 -- AttributeError: 'module' object has no attribute
- Now requires the ``six`` module
- FIx #22 -- No blank space after header does not render codeblocks


- Complete overhaul of **pydoc-markdown** employing MkDocs and the
Markdown module.


.. raw:: html

<p align="center">

Copyright © 2017 Niklas Rosenstein

.. raw:: html


Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pydoc-markdown-2.0.3.tar.gz (16.5 kB) Copy SHA256 hash SHA256 Source None May 3, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page