Five Tips for Automatic Python Documentation | by Louis de Bruijn | Towards Data Science

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 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.
Previously, I wrote on the importance of writing docstrings, with a focus on Sphinx documentation.
betterprogramming.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 👇
towardsdatascience.com
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: docstemplates_dir: docs/templatesrepo: https://github.com/LouisdeBruijn/Mediumversion: 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
Add the pages, sources, and functions to be documented to this mkgendocs.yml file.Run $ gendocs --config mkgendocs.yml to create the static MkDocs pages with the documentation of these functions.
Add the pages, sources, and functions to be documented to this mkgendocs.yml file.
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.
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.
Our last step is to add each automation step into a Git hook in the pre-commit-config.yaml. More on pre-commit Git hooks in the story below👇
betterprogramming.pub
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/.
With the automation steps presented in this story, you can automatically create beautiful Python documentation in MkDocs. If you have any questions, feel free to contact me. Happy coding!
Looking for more Python clean coding tips? Find them here 👇