Python Automatic Documentation Generator

The Python Automatic Documentation Generator have a long phase during building a site, which usually takes place before you even start coding. Knowing and being able to use the python automatic documentation generator for your site also gives you the edge because of the steady increase in demand for high quality websites backed with strong support service.

Python automatic documentation generator is an application which helps in creating the python documentation and makes it easy for developers to create a quality documentation. This article is worth reading and if you’re working with Python then this article will assist you greatly.

Automated Documentation can be a helpful way to reduce your project costs and maintenance efforts. It safeguards you from the errors occurring in your code base, it enhances readability and legibility of the existing code. Other than these, there are plenty of other benefits that come with Automated Documentation. There are many tools available on the web which facilitate automatic documentation generation in Python projects. However, today I am going to share with you some of the most reliable and trending tools on Python Automatic Documentation Generation Process which have helped many developers worldwide cope up with rising project demands and exceed their customer’s expectations.

Python Documentation Generator is a powerful tool that automatically generates full documentation for python project in various formats. Project information, such as the project name, author, and version are pulled directly from the setup.py file of the project being documented.

Five Tips for Automatic Python Documentation

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

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.https://towardsdatascience.com/media/3fe169c5858a23bfd1679898044363d6

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.

Automate type-hints to docstrings

Previously, I wrote on the importance of writing docstrings, with a focus on Sphinx documentation.Start Writing Python DocstringsSimplify your life and the life of whoever is trying to read your codebetterprogramming.pub

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.

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.

Interested in automating type-hints to docstrings? Read the story below 👇Python Type-hints & DocstringsAutomatically insert variables types from Python’s type-hints (3.5+) in Google-style docstrings.towardsdatascience.com

Automate docstrings to MkDocs

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

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.

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

Tie everything together in pre-commit Git hooks

Our last step is to add each automation step into a Git hook in the pre-commit-config.yaml.

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.

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/.

Getting Started with Sphinx / Autodoc: Part 1

In this article, we’ll be going through the (very) basics of generating documentation from docstrings in your Python code. It is a bit of a grind, but after you do it once, it will be easy to repeat the process in every new project.

For our purposes, we will assume that you (1) believe in the value of documenting your code; (2) wish to generate docs from your docstrings and (3), have chosen to use Sphinx to accomplish the work.

Finally, it is assumed that you have already setup a distinct virtual environment for your application. For those interested, I really like the pyenv environment manager. It even has a handy installer.

Step 1: Installing Sphinx

You’ll need to install sphinx via pip. At a minimum you will need version 1.3, but unless you have good reason, you should install the most recent version.

$ pip install sphinx

Step 2: Setup your Project with Quickstart

When you install the sphinx package a number of command line utilities are setup as well.

One of those, sphinx-quickstart will quickly generate a basic configuration file and directory structure for your documentation.

Run this command at the base directory of your project (i.e. the Git repo root). It will ask you a number of questions that will determine it’s actions. You can generally accept the default values, but here are some suggestions of when to deviate from the default:

• Root path for the documentation: ./docs
• autodoc: automatically insert docstrings from modules (y/n): y
• coverage: checks for documentation coverage (y/n) [n]: y

After the program has run, you’ll notice that a new ./docs folder exists in your project directory. In addition, there are three new files in that folder: conf.py, index.rst, andMakefile.

Step 3: Adjusting the conf.py File

The default conf.py file generated by the quickstart utility is about 170 lines long, so I won’t include the whole thing here. There are however, a couple of items that we need to update before continuing.

Tell Sphinx the Location of your Python Package

The first thing that we need to do is indicate where the Python package that contains your program code is in relation to the conf.py file. If your directory structure looks like this:

You will need to indicate in the conf.py file that Sphinx must go “up” one directory level to find the Python package.

The place to put this is at the end of the first section of the configuration file. Just before the General Configuration settings, you’ll see this:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

If it wasn’t commented out, it would indicate that your package is in the same directory as the conf.py file. You’ll need to change it to this:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Add “Napoleon” to the list of Sphinx Extensions to Use

Out of the box, Sphinx only understands docstrings written in traditional reStructuredText. If you’ve had the, ahem, privilege of working with such docstrings, you’ll know that they are a pain to write and not at all human friendly to read when looking at them directly in the source code.

The Napoleon extension enables Sphinx to understand docstrings written in two other popular formats: NumPy and Google.

All we have to do is add sphinx.ext.napoleon to the extensions list. When you are done, it should look like this:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

Step 4: Update index.rst

At this point, we could actually run the build process to generate our documentation. But it would be pretty disappointing. Here’s is what we’d get:

As much as I would like for Sphinx to go and find our docstrings for us and arrange them nicely without any further configuration, it isn’t quite that magical.

To move forward, we will have to do some minor modifications to our index.rst file, which currently looks like this:

.. Getting Started with Sphinx documentation master file, created by
   sphinx-quickstart on Mon Nov 13 11:41:03 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.Welcome to Getting Started with Sphinx's documentation!
=======================================================.. toctree::
   :maxdepth: 2
   :caption: Contents:Indices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Let’s start by getting rid of the comment at the top which is just noise:

Welcome to Getting Started with Sphinx's documentation!
=======================================================.. toctree::
   :maxdepth: 2
   :caption: Contents:Indices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Now, while there are a number of things that we could do here, we are going to limit ourselves to the bare minimum to keep this post to a somewhat reasonable length.

Do you see that .. toctree:: line? That is what Sphinx calls a directive. We need to add autodoc directives to our index.rst file so that Sphinx knows what code objects we wish to use the autodoc extension on.

I’ll go ahead and add one indicating to Sphinx that I want it to document the public members of my main.py module inside the my_project package:

Welcome to Getting Started with Sphinx's documentation!
=======================================================.. automodule:: my_project.main
    :members:.. toctree::
   :maxdepth: 2
   :caption: Contents:Indices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Step 5: Write Your Docstrings

We will not cover the how to write docstrings in Numpy or Google style in this post.

However, here is the code from main.py which contains a couple of simple NumPy style docstrings that will be picked up by our autodoc directive:https://eikonomega.medium.com/media/20bfdcda8a38f82659e4918c7e0a4808

Step 6: Generate your Docs!

Now it’s time to reap the rewards of your labor. Make sure you are in the ./docs directory and execute the following: make html

If you’ve been following along thus far, you should see something like this:

Running Sphinx v1.6.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

As long as you see that glorious build succeeded message at the end, you are ready to go and behold your beautiful creation.

At the command line, execute open _build/html/index.html (or just open up that page in your browser manually) and you should see something like this:

As a developer, we all know the importance of code documenting: Good code is not only self-explanatory but also well-documented. However, we also struggle with keeping documents up to date, especially if we maintain the source code and its documents separately. If we can generate the document based on the source code or based on the code comments, we have a better chance to keep the document up to date.

Sphinx is a tool to build documents from the code. It supports many programming languages, and it is widely used in Python projects, including the official Python website. The official website of Sphinx provides much useful information and reference. However, for whom to use Sphinx for the first time, the official website may be overwhelming. At least, that is my experience when I tried to use Sphinx the first time. Therefore, I wrote this article, and hopefully, this article could provide a simple and straightforward tutorial for a newbie of Sphinx.

Conclusion

A Python generator is an awesome tool that helps in creating the best auto documentation for your code. The generator is easy to use, and allows you to focus on more important aspects of the development such as more complex and difficult aspects of programming tasks.

You need to ensure your project is easy to maintain and understand. This can be done in a number of ways, but one of the easiest ways is writing comments explaining your code. But this takes time, often requires you to go back into a project you haven’t worked on in weeks which can result in forgetting to document something.