Create Python API documentation in Markdown format
Project description
**pydoc-markdown** uses `MkDocs <www.mkdocs.org/>`__ and extended
`Markdown <https://pythonhosted.org/Markdown/>`__ syntax to generate
beautiful Python API documentation. It is highly configurable and can be
extended to work with arbitrary programming languages, see the
`Extension
API <https://niklasrosenstein.github.io/pydoc-markdown/extensions/loader/>`__.
Highly insipired by the `Keras <https://keras.io/>`__ Documentation.
**Todo**
- [ ] 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...``)
Building
========
The ``pydocmd`` command is a wrapper around ``mkdocs`` and supports the
same commands. It will simply autogenerate the documentation files and
then invoke MkDocs. If you only want to run the auto-generation, simply
use the ``generate`` subcommand.
::
$ pydocmd --help
usage: pydocmd [-h] {generate,build,gh-deploy,json,new,serve}
positional arguments:
{generate,build,gh-deploy,json,new,serve}
optional arguments:
-h, --help show this help message and exit
Configuration
=============
**pydoc-markdown** only takes over the task of generating the Markdown
documentation that can then be processed with
`MkDocs <www.mkdocs.org/>`__. However, it can still combine both parts
of the build process in a single command. You can put all configuration
for `MkDocs <www.mkdocs.org/>`__ into the ``pydocmd.yml`` configuration,
or have it in a separate ``mkdocs.yml`` file.
**pydocmd.yml**
.. code:: yaml
site_name: "foobar Documentation"
generate:
- baz/cool-stuff.md:
- foobar.baz: # Module docstring
# Indenting the following items to give them a smaller header size
- foobar.baz.CoolClass+ # Class docstring (+ to include members)
- foobar.baz.some_function # Function docstring
# MkDocs pages configuration, with some sugar.
pages:
- Home: index.md << ../README.md
- foobar.baz:
- Cool Stuff: baz/cool-stuff.md
docs_dir: sources # default
gens_dir: _build/pydocmd # default (-> MkDocs docs_dir)
site_dir: _build/site # default
theme: readthedocs # default
loader: pydocmd.loader.PythonLoader # default
preprocessor: pydocmd.preprocessor.Preprocessor # default
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.0 (devtip)
---------------
- Complete overhaul of **pydoc-markdown** employing MkDocs and the
Markdown module.
--------------
.. raw:: html
<p align="center">
Copyright © 2017 Niklas Rosenstein
.. raw:: html
</p>
`Markdown <https://pythonhosted.org/Markdown/>`__ syntax to generate
beautiful Python API documentation. It is highly configurable and can be
extended to work with arbitrary programming languages, see the
`Extension
API <https://niklasrosenstein.github.io/pydoc-markdown/extensions/loader/>`__.
Highly insipired by the `Keras <https://keras.io/>`__ Documentation.
**Todo**
- [ ] 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...``)
Building
========
The ``pydocmd`` command is a wrapper around ``mkdocs`` and supports the
same commands. It will simply autogenerate the documentation files and
then invoke MkDocs. If you only want to run the auto-generation, simply
use the ``generate`` subcommand.
::
$ pydocmd --help
usage: pydocmd [-h] {generate,build,gh-deploy,json,new,serve}
positional arguments:
{generate,build,gh-deploy,json,new,serve}
optional arguments:
-h, --help show this help message and exit
Configuration
=============
**pydoc-markdown** only takes over the task of generating the Markdown
documentation that can then be processed with
`MkDocs <www.mkdocs.org/>`__. However, it can still combine both parts
of the build process in a single command. You can put all configuration
for `MkDocs <www.mkdocs.org/>`__ into the ``pydocmd.yml`` configuration,
or have it in a separate ``mkdocs.yml`` file.
**pydocmd.yml**
.. code:: yaml
site_name: "foobar Documentation"
generate:
- baz/cool-stuff.md:
- foobar.baz: # Module docstring
# Indenting the following items to give them a smaller header size
- foobar.baz.CoolClass+ # Class docstring (+ to include members)
- foobar.baz.some_function # Function docstring
# MkDocs pages configuration, with some sugar.
pages:
- Home: index.md << ../README.md
- foobar.baz:
- Cool Stuff: baz/cool-stuff.md
docs_dir: sources # default
gens_dir: _build/pydocmd # default (-> MkDocs docs_dir)
site_dir: _build/site # default
theme: readthedocs # default
loader: pydocmd.loader.PythonLoader # default
preprocessor: pydocmd.preprocessor.Preprocessor # default
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.0 (devtip)
---------------
- 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.0.dev0.tar.gz
(12.6 kB
view hashes)
Close
Hashes for pydoc-markdown-2.0.0.dev0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2737f042c7094be103c8655fab444d1b7dadf6d9b659fa7708ba2be226d848ca |
|
MD5 | 26ff3c4c9364af9645c27a531349d0a9 |
|
BLAKE2b-256 | 82275ca6e9167935e4a2587445a7119bd043a57fc187cb5c9eaa079e51579975 |