Create Python API documentation in Markdown format
Project description
pydocmd
=======
– *insipired by the `Keras <https://keras.io/>`__ Documentation*
Pydocmd uses `MkDocs <http://www.mkdocs.org/>`__ and extended
`Markdown <https://pythonhosted.org/Markdown/>`__ syntax to generate
beautiful Python API documentation.
**Todo**
- [x] Support ``+`` suffix to include documented members of a
module/class
- [ ] 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...``)
Installation
============
::
pip install pydoc-markdown
pip install git+https://github.com/NiklasRosenstein/pydoc-markdown.git # latest development version
Usage
=====
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+ > docs.md
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
supported.
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.
generate:
- baz/cool-stuff.md:
- foobar.baz:
- foobar.baz.CoolClass+ # (+ to include members)
- foobar.baz.some_function
- baz/more-stuff.md:
- 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.
pages:
- Home: index.md << ../README.md
- foobar.baz:
- Cool Stuff: baz/cool-stuff.md
# 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.
additional_search_paths:
- ..
Syntax
======
Cross-references
----------------
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 ``#X~some.reference.name`` can be used, where
``X`` is the number of elements to keep. If ``X`` is omitted, it will be
assumed 1. Example: ``#~some.reference.name`` 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
``#Signal#s``.
**pydoc-markdown** can be extended to find other cross-references using
the `Extension
API <https://niklasrosenstein.github.io/pydoc-markdown/extensions/loader/>`__.
Sections
--------
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
font.
(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.
::
```python
>>> for i in range(100):
...
```
--------------
Changes
=======
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)
v2.0.1
------
- 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
'signature'
- Now requires the ``six`` module
- FIx #22 -- No blank space after header does not render codeblocks
v2.0.0
------
- Complete overhaul of **pydoc-markdown** employing MkDocs and the
Markdown module.
--------------
.. raw:: html
<p align="center">
Copyright © 2017 Niklas Rosenstein
.. raw:: html
</p>
=======
– *insipired by the `Keras <https://keras.io/>`__ Documentation*
Pydocmd uses `MkDocs <http://www.mkdocs.org/>`__ and extended
`Markdown <https://pythonhosted.org/Markdown/>`__ syntax to generate
beautiful Python API documentation.
**Todo**
- [x] Support ``+`` suffix to include documented members of a
module/class
- [ ] 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...``)
Installation
============
::
pip install pydoc-markdown
pip install git+https://github.com/NiklasRosenstein/pydoc-markdown.git # latest development version
Usage
=====
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+ > docs.md
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
supported.
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.
generate:
- baz/cool-stuff.md:
- foobar.baz:
- foobar.baz.CoolClass+ # (+ to include members)
- foobar.baz.some_function
- baz/more-stuff.md:
- 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.
pages:
- Home: index.md << ../README.md
- foobar.baz:
- Cool Stuff: baz/cool-stuff.md
# 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.
additional_search_paths:
- ..
Syntax
======
Cross-references
----------------
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 ``#X~some.reference.name`` can be used, where
``X`` is the number of elements to keep. If ``X`` is omitted, it will be
assumed 1. Example: ``#~some.reference.name`` 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
``#Signal#s``.
**pydoc-markdown** can be extended to find other cross-references using
the `Extension
API <https://niklasrosenstein.github.io/pydoc-markdown/extensions/loader/>`__.
Sections
--------
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
font.
(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.
::
```python
>>> for i in range(100):
...
```
--------------
Changes
=======
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)
v2.0.1
------
- 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
'signature'
- Now requires the ``six`` module
- FIx #22 -- No blank space after header does not render codeblocks
v2.0.0
------
- Complete overhaul of **pydoc-markdown** employing MkDocs and the
Markdown module.
--------------
.. raw:: html
<p align="center">
Copyright © 2017 Niklas Rosenstein
.. raw:: html
</p>
Project details
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.
Source Distribution
pydoc-markdown-2.0.3.tar.gz
(16.5 kB
view hashes)