@@ -1,9 +1,9 @@
`pdoc` extracts documentation of:
- modules (including submodules),
- functions (including methods, properties, coroutines ...),
- classes, and
- variables (including globals, class variables, and instance variables).
* modules (including submodules),
* functions (including methods, properties, coroutines ...),
* classes, and
* variables (including globals, class variables, and instance variables).
Documentation is extracted from live objects' [docstrings]
using Python's `__doc__` attribute[^execution]. Documentation for
@@ -12,29 +12,27 @@ variables is found by examining objects' abstract syntax trees.
[docstrings ]: https://docs.python.org/3/glossary.html#term-docstring
[^execution]:
Documented modules are executed in order to provide `__doc__`
attributes. Any non-fenced global code in imported modules will
affect the current environment.
Documented modules are executed in order to provide `__doc__`
attributes. Any non-fenced global code in imported modules will
affect the current environment.
## What objects are documented?
What objects are documented?
----------------------------
`pdoc` only extracts _public API_ documentation.[^public]
All objects (modules, functions, classes, variables) are only
considered public if their _identifiers don't begin with an
underscore_ ( \\\ _ ).[^private]
underscore_ ( \\ _ ).[^private]
[^public]:
Here, public API refers to the API that is made available
to your project end-users, not the public API e.g. of a
private class that can be reasonably extended elsewhere
by your project developers.
Here, public API refers to the API that is made available
to your project end-users, not the public API e.g. of a
private class that can be reasonably extended elsewhere
by your project developers.
[^private]:
Prefixing private, implementation-specific objects with
an underscore is [a common convention].
Prefixing private, implementation-specific objects with
an underscore is [a common convention].
[a common convention ]: https://docs.python.org/3/tutorial/classes.html#private-variables
@@ -50,8 +48,9 @@ By transitivity, sub-objects of non-public objects
(e.g. submodules of non-public modules, methods of non-public classes etc.)
are not public and thus not documented.
## Where does `pdoc` get documentation from?
Where does `pdoc` get documentation from?
-----------------------------------------
In Python, objects like modules, functions, classes, and methods
have a special attribute `__doc__` which contains that object's
documentation string ([docstring ][docstrings]).
@@ -68,7 +67,7 @@ and shows how to access its contents:
It's pretty much the same with classes and modules.
See [PEP-257] for Python docstring conventions.
[pep -257
[PEP -257
These docstrings are set as descriptions for each module, class,
function, and method listed in the documentation produced by `pdoc` .
@@ -77,6 +76,7 @@ function, and method listed in the documentation produced by `pdoc`.
important ways: by allowing methods to inherit docstrings, and
by introducing syntax for docstrings for variables.
### Docstrings inheritance
`pdoc` considers methods' docstrings inherited from superclass methods',
@@ -104,16 +104,17 @@ it will automatically attach the docstring for `A.test` to
`B.test` if `B.test` does not define its own docstring.
In the default HTML template, such inherited docstrings are greyed out.
### Docstrings for variables
Python by itself [doesn't allow docstrings attached to variables ][pep -224].
Python by itself [doesn't allow docstrings attached to variables ][PEP -224].
However, `pdoc` supports docstrings attached to module (or global)
variables, class variables, and object instance variables; all in
the same way as proposed in [PEP-224], with a docstring following the
variable assignment.
For example:
[pep -224
[PEP -224
module_variable = 1
\" ""Docstring for module_variable.\" ""
@@ -138,8 +139,9 @@ Class and instance variables can also [inherit docstrings].
[inherit docstrings ]: #docstrings-inheritance
## Overriding docstrings with `__pdoc__`
Overriding docstrings with `__pdoc__`
-------------------------------------
Docstrings for objects can be disabled or overridden with a special
module-level dictionary `__pdoc__` . The _keys_
should be string identifiers within the scope of the module or,
@@ -166,53 +168,56 @@ attaching a docstring to something. A good example of this is a
`types` , `names` and `rows` members.
.. note::
The assignments to `__pdoc__` need to be placed where they'll be
executed when the module is imported. For example, at the top level
of a module or in the definition of a class.
The assignments to `__pdoc__` need to be placed where they'll be
executed when the module is imported. For example, at the top level
of a module or in the definition of a class.
## Supported docstring formats
Supported docstring formats
---------------------------
Currently, pure Markdown (with [extensions]), [numpydoc],
and [Google-style] docstrings formats are supported,
along with some reST directives.
\ *
*[reST]: reStructuredText
[extensions]: https://python-markdown.github.io/extensions/#officially-supported-extensions
[numpydoc]: https://numpydoc.readthedocs.io/
[Google-style]: http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
### Supported reST directives
The following reST directives should work:
- specific and generic [admonitions],
- [`.. image::` ][image] or `.. figure::` (without options),
- [`.. include::` ][include], with support for the options:
* specific and generic [admonitions],
* [`.. image::`][image] or `.. figure::` (without options),
* [`.. include::`][include], with support for the options:
`:start-line:`, `:end-line:`, `:start-after:` and `:end-before:`.
- `.. versionadded::`
- `.. versionchanged::`
- `.. deprecated::`
- `.. todo::`
* `.. versionadded::`
* `.. versionchanged::`
* `.. deprecated::`
* `.. todo::`
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[image]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#images
[include]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment
## Linking to other identifiers
Linking to other identifiers
----------------------------
In your documentation, you may refer to other identifiers in
your modules. When exporting to HTML, linking is automatically
done whenever you surround an identifier with [backticks ](` ).
done whenever you surround an identifier with [backticks] ( \\` ).
The identifier name must be fully qualified, for example
<code>\\`pdoc.Doc.docstring\\`</code> is correct (and will link to
`pdoc.Doc.docstring`) while <code>\\`Doc.docstring\\`</code> is _not_.
[backticks]: https://en.wikipedia.org/wiki/Grave_accent#Use_in_programming
## Command-line interface
Command-line interface
----------------------
[cmd]: #command-line-interface
`pdoc` includes a feature-rich "binary" program for producing
HTML and plain text documentation of your modules.
To produce HTML documentation of your whole package in subdirectory
@@ -228,18 +233,19 @@ docstrings for it, run:
To re-build documentation as part of your continuous integration (CI)
best practice, i.e. ensuring all reference links are correct and
up-to-date, make warnings error loudly by settings the environment
variable [`PYTHONWARNINGS` ][pythonwarnings ] before running pdoc:
variable [`PYTHONWARNINGS`][PYTHONWARNINGS ] before running pdoc:
$ export PYTHONWARNINGS='error::UserWarning'
[pythonwarnings ]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS
[PYTHONWARNINGS ]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS
For brief usage instructions, type:
$ pdoc --help
## Programmatic usage
Programmatic usage
------------------
The main entry point is `pdoc.Module` which wraps a module object
and recursively imports and wraps any submodules and their members.
@@ -276,18 +282,19 @@ For importing arbitrary modules/files, use `pdoc.import_module`.
Alternatively, use the [runnable script][cmd] included with this package.
## Custom templates
Custom templates
----------------
To override the built-in HTML/CSS and plain text templates, copy
the relevant templates from `pdoc/templates` directory into a directory
of your choosing and edit them. When you run [pdoc command][cmd]
afterwards, pass the directory path as a parameter to the
`--template-dir` switch.
.. tip::
If you find you only need to apply minor alterations to the HTML template,
see if you can do so by overriding just some of the following, placeholder
sub-templates:
If you find you only need to apply minor alterations to the HTML template,
see if you can do so by overriding just some of the following, placeholder
sub-templates:
* _config.mako_: Basic template configuration, affects the way templates are rendered.
* _head.mako_: Included just before `</head>`. Best for adding resources and styles.
@@ -300,25 +307,28 @@ If working with `pdoc` programmatically, _prepend_ the directory with
modified templates into the `directories` list of the
`pdoc.tpl_lookup` object.
## Compatibility
Compatibility
-------------
`pdoc` requires Python 3.5+.
The last version to support Python 2.x is [pdoc3 0.3.x].
[pdoc3 0.3.x]: https://pypi.org/project/pdoc3/0.3.11/
## Contributing
Contributing
------------
`pdoc` is [on GitHub]. Bug reports and pull requests are welcome.
[on github ]: https://github.com/pdoc3/pdoc
[on GitHub ]: https://github.com/pdoc3/pdoc
## License
License
-------
`pdoc` is licensed under the terms of GNU [AGPL-3.0]{: rel=license} or later,
meaning you can use it for any reasonable purpose and remain in
complete ownership of all the documentation you produce,
but you are also encouraged to make sure any upgrades to `pdoc`
itself find their way back to the community.
[agpl -3.0
[AGPL -3.0]: https://www.gnu.org/licenses/agpl-3.0.html
