Python How to Generate Documentation

Python How to Generate Documentation

by

Generating documentation using Python string formatting syntax makes writing documentation in Python easy. This article explains how you can go about it. The official Python documentation generator is also explained in greater detail and compared against other popular Documentation Generators for Python  you could use.

Python How to Generate Documentation – Learn Python in simple and easy steps starting from basic to advanced concepts with examples including Python Syntax Object Oriented Language, Methods, Tuples, Tools/Utilities, Exceptions Handling, Sockets, GUI, Extentions, XML Programming.

Documentation is essential for creating beautiful and elegant applications. We at Webelieve find the document generation tool that is helping us in achieving our goals. The thing is, there are many options out there to choose from. Each with its own strengths, weaknesses, features and support issues. So choosing the right documentation generation tool for your project can be difficult.

This page is primarily about tools that help, specifically, in generating documentation for software written in Python, i.e., tools that can use language-specific features to automate at least a part of the code documentation work for you. The last section also lists general documentation tools with no specific support for Python (though some of them are themselves written in Python).

Code of conduct

A code of conduct file (often named “CONDUCT”) is used to define community standards, identify a welcoming and inclusive project, and outline procedures for handling abuse. GitHub provides an excellent guide for adding a code of conduct to your project. A code of conduct helps the community feel safe, respected, and welcome to contribute to your package. Without it, others may not want to contribute to your package, and conflicts may arise among contributors with conflicting ideas.

Python docstrings

Python modules are usually documented using docstrings. You can read a module’s docstrings from the Python interactive prompt with the help() function. For example:

import distutils
help(distutils)

The help() function uses Python’s standard pydoc module, as does the pydoc command that comes with Python.

Automatic Python API documentation generation tools

  • autosummary, an extension for the Sphinx documentation tool.
  • autodoc, a Sphinx-based processor that processes/allows reST doc strings.
  • pdoc, a simple Python 3 command line tool and library to auto-generate API documentation for Python modules. Supports Numpydoc / Google-style docstrings, doctests, reST directives, PEP 484 type annotations, custom templates …
  • pdoc3, a fork of pdoc for Python 3 with support for Numpydoc / Google-style docstrings, doctests, LaTeX math, reST directives, PEP 484 type annotations, custom templates …
  • PyDoc, a documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as pydoc.
  • pydoctor, a replacement for now inactive Epydoc, born for the needs of Twisted project.
  • Doxygen can create documentation in various formats (HTML, LaTeX, PDF, …) and you can include formulas in your documentation (great for technical/mathematical software). Together with Graphviz, it can create diagrams of your code (inhertance diagram, call graph, …). Another benefit is that it handles not only Python, but also several other programming languages like C, C++, Java, etc.

No longer under development

Documentation processing tools

Other projects that can be used to produce API documentation

  • XIST – an XML based extensible HTML generator written in Python.
  • HtmlGen – a Python library for generating HTML documents.

Other documentation processing tools

  • Pandoc — written in Haskell, this tool can read and write a number of formats (including reST).
  • Rippledoc (formerly known as Gouda) — a command-line tool written in Clojure (using Pandoc under the hood) to generate multi-chapter html documents from Markdown text files.

Five Tips for Automatic Python Documentation

Create beautiful Python documentation in MkDocs & Material with these five automation steps and pre-commit Git hooks

MkDocs automatically generation documentation
An automatically generated function documentation with Google-style docstring in MkDocs

In this story, you will learn how to automatically generate documentation from Python modules with a bit of magic in our custom functions, the package mkgendocs, pre-commit Git hooks, and MkDocs. We will touch upon the following elements

  • MkDocs & Material installation
  • Automate type-hints to docstrings
  • Automate docstrings to MkDocs with mkgendocs
  • Automate the documentation of new Python functions
  • Tie everything together in pre-commit Git hooks

MkDocs & Material installation

MkDocs is a static site generator for building project documentation and together with the Material framework, it simply looks gorgeous. First, we need to install a heap of packages in order to use all of the functionalities of MkDocs. All of these packages are pip-installable.

MkDocs uses a configuration file mkdocs.yml, where you can enable all of the functionalities and packages installed above. Please find mine here. It includes references to the /docs and /docs_assets folders with the theme.

Docstrings are an essential tool to document your functions. Python 3.5+ introduced type-hints, a way to assign static types to variables directly in the function arguments.

Several IDEs such as Pycharm, Visual Studio, and Sublime Text support automatic docstring generation. They do not however infer variable types from type-hints yet, which means that you have to fill both the variable type and descriptions in the docstrings.

Pycharm IDE docstring generation
Pycharm (almost) automatic docstring generation

Shown above is the implementation in Pycharm with Google-style docstrings. You are free to use other styles (such as reStructuredText/Sphinx or NumPy), but I found a package that exclusively works with Google-style docstrings for our next automation steps.

Automate docstrings to MkDocs

MkDocs function documentation with Google-style docstring
MkDocs page automatically inferred from function docstring

The package mkgendocs automatically translates Google-style docstrings into pages with the description of Python functions. It uses a configuration file mkgendocs.yml. The configuration file looks like this

sources_dir: docs
templates_dir: docs/templates
repo: https://github.com/LouisdeBruijn/Medium
version: masterpages:
  - page: "scripts/base/base.md"
    source: "Python tips/base.py"
    functions:
      - parse_arguments
      - print_df
      - unescape_html
      - equal_array_items

Two manual steps for the use of this package are

  1. Add the pages, sources, and functions to be documented to this mkgendocs.yml file.
  2. Run $ gendocs --config mkgendocs.yml to create the static MkDocs pages with the documentation of these functions.

Next up, we will automate both steps by first creating a script to pre-fill our configurations file, and next attach both steps in a pre-commit Git hook.

Automate the documentation of new functions

automate MkDocs from docstring
function to fill mkgendocs config from docstrings

First, I wrote a module automate.py with a function automate_mkdocs_from_docstring() to fill the mkgendocs.yml configurations file with all the Python functions in modules (scripts) in a repository.

automate_mkdocs_from_docstring() uses Pathlib to read the Python scripts in a directory and extract the function names. It saves both the module and the function names in a dictionary and uses this to overwrite the mkgendocs.yml. This way we can automatically fil the configurations file for the mkgendocs package.

run automation of MkDocs from docstrings
custom automation step from docstrings to MkDocs

Second, we will include both the execution of automate.py and the $ gendocs --config mkgendocs.yml in a pre-commit Git hook.

We’re adding the two mandatory steps for the automatic generation of MkDocs pages with the mkgendocs package in a pre-commit Git hook. These hooks allow us to execute a Python script with an entry bash command.

This way, when we create or remove Python functions anywhere in our repository, they will automatically be added to the mkgendocs configuration file, automatically creating static MkDocs pages and building the documentation website.

automatic documentation with pre-commit Git hooks GIF
Automatic documentation in pre-commit Git hooks

The only thing left to do is to run our MkDocs site with $ mkdocs serve and find our documentation at http://127.0.0.1:8000/.

Sphinx

Sphinx is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text.

There is also great, free hosting for your Sphinx docs: Read The Docs. Use it. You can configure it with commit hooks to your source repository so that rebuilding your documentation will happen automatically.

When run, Sphinx will import your code and using Python’s introspection features it will extract all function, method, and class signatures. It will also extract the accompanying docstrings, and compile it all into well structured and easily readable documentation for your project.

ProProfs Knowledge Base 

ProProfs Knowledge Base is a simple and versatile tool that helps you create software documentation of top-notch quality for your end-users. Packed with bespoke features, the tool simplifies software documentation and assists you at all stages of content creation, right from authoring to publishing. 

If you are worried about where to start, fret not. The tool offers ready-to-use templates that give you a good starting point to build content. You can write and style the entire software documentation just the way you want with the wide array of formatting features ProProfs Knowledge Base provides.

In addition to this, features like single sourcing, revision history, import, and export, further improve the process of creating and managing online documentation. 

Rating: 4.6/5

Pricing: Starts at $30/author/month

Process Street 

Process Street is another tool for software documentation that deserves your attention. It comes with a simple interface that lets you build structured software documentation for your end-users. With intuitive keyboard shortcuts and drag and drop functionality, Process Street makes document authoring easy for everyone in your development team. You can also add visual and audio elements to your document and turn it into a media-rich information resource. 

In addition to this, it allows developers to work in collaboration and take full accountability for the assigned software development tasks. 

Rating: 4.6/5

Pricing: Starts at $25/user/month

reStructuredText

Most Python documentation is written with reStructuredText. It’s like Markdown, but with all the optional extensions built in.

The reStructuredText Primer and the reStructuredText Quick Reference should help you familiarize yourself with its syntax.

Pros of creating good documentation:

  1. Increases information exchange between team members— this single reason is just so powerful!
  2. Decreases onboarding time of new members

3. Helps to organize big projects (helps to see the big picture)

4. Increases team member awareness of how the whole project is organized

5. Increases development speed — finding information is faster and thus development is faster

6. Promotes standards and consistency

Cons of creating documentation?

  1. Requires time (and money) — sometimes a project can’t afford to spend time on documentation.

2. It’s hard to keep it up-to-date, especially in startup projects with rapid changes

3. Creating documentation is not a “pleasant” activity for the developers (compared to creating code) — some developers don’t like to create the documentation, they will be demotivated when asked to do it.

Cons of bad documentation?

  1. “Out-of-date” documentation can lead to misunderstandings and slower development

2. Can get fragmented — it’s hard to maintain one, consistent documentation.

Taking the pros and cons into account it would seem sensible to either create good, up-to-date documentation or not create it at all. But there are tools that can help and decrease the human factor. Autogenerated documentation tools require less effort from people and can create valuable documentation automatically.

Conclusion

A lot of people don’t know about this or are confused about what it is. Python Documentation Generator is actually a very simple way to add some great components to your python code and make your code look quite professional.

Python developers may often face the challenge of how to create documentation for their Python projects. If you are not a big fan of creating and editing man pages, or writing extensive API descriptions, then you can use python doc generators to generate high quality API documentation for your Python applications.

Leave a Comment