How do I create documentation from doc strings in Python?

To create documentation from doc strings, we can use the following packages and modules −

• Pydoc
• Epydoc
• Sphinx

Let us understand them one by one −

Pydoc

The pydoc module can create HTML from the doc strings in your Python source code.

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or s**ed to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. For example, running -

pydoc sys

at a shell prompt will display documentation on the sys module, in a style similar to the manual pages shown by the Unix man command. The argument to pydoc can be the name of a function, module, or package, or a dotted reference to a class, method, or function within a module or module in a package.

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting web browsers.

• pydoc -n <hostname> will start the server listening at the given hostname. By default the hostname is ‘localhost’ but if you want the server to be reached from other machines, you may want to change the host name that the server responds to.

• pydoc -b will start the server and additionally open a web browser to a module index page.

Epydoc

Create API documentation purely from docstrings using the epydoc package.

Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. For an example of epydoc's output, see the API documentation for epydoc itself (html, pdf). A lightweight markup language called epytext can be used to format docstrings, and to add information about specific fields, such as parameters and instance variables. Epydoc also understands docstrings written in reStructuredText, J**adoc, and plaintex

Sphinx

Sphinx makes it easy to create intelligent and beautiful documentation. Following are the features−

• Output formats − HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.

• Extensive cross-references − semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information.

• Hierarchical structure − easy definition of a document tree, with automatic links to siblings, parents and children.

• Automatic indices − general index as well as a language-specific module indices.

• Code handling − automatic highlighting using the Pygments highlighter.

• Extensions − automatic testing of code snippets, inclusion of docstrings from Python modules via built-in extensions, and much more functionality via third-party extensions.

• Themes − modify the look and feel of outputs via creating themes, and re-use many thirdparty themes.

• Contributed extensions − dozens of extensions contributed by users; most of them installable from PyPI.