How to document Python code?
… in order to create HTML documentation files.
Introduction
This document explains how to comment Python code in order to create documentation files in the HTML format. This is a possible simple way to do it, but there are more functionalities provided by the component we will be using.
What to expect?
Here is a simple example of an expected output:
What we will use
To do the documentation we will use the pdoc component. This is a simple tool to generate HTML documentation.
We can find more information about pdoc on the official site. https://pdoc.dev/docs/pdoc.html
Installation
To install pdoc, we will use pip3 install command.
So, on a command line, we should run the following command:
$pip3 install pdoc3
Here is an example of an install command execution:
Documentation rules
There are some rules to put on our code comments so that they can be considered while generating the html file. Here are some of them in order to have pages with formats similar to the following:
Rule 1 — Class description
The class description should be inserted as an inner-tabbed text and limited by 3 double quotes. It is advisable to start and end the quotes in different lines.
Here is an example:
Rule 2 — Method description
The method description should be inserted as an inner-tabbed text by 3 double quotes. It is advisable to start and end the quotes in different lines.
Rule 3 — Isolate parameters
To highlight the parameter names, it is advisable to add the ` (grave accent) character around the parameter name.
HTML document generation
To generate the HTML document, here is the command syntax format:
$ pdoc — html-dir=<<HTML_FOLDER>> — html <<FILES_TO_INCLUDE>> — force
Where:
<<HTML_FOLDER>> is the output folder path where pdoc will store the html generated files.
<<FILES_TO_INCLUDE>> is the name of the .py file that pdoc will read and generate documentation.
- Example: module_abc.py (one only file)
It is also the pattern of the .py files that pdoc will read to generate documentation.
- Example: module_*.py (all files which name starts with module_)
- -force in case the output file already exists, the command will force its replacement for a new generated one.
Additional notes
Here are some additional notes that can be seen when writing the pdoc -h command on a shell.
Here is the list of arguments when running pdoc.
Usage
pdoc [-h] [ — version] [-c OPTION=VALUE] [ — filter STRING] [-f]
[ — html | — pdf] [-o DIR] [ — template-dir DIR] [ — close-stdin]
[ — http HOST:PORT] [ — skip-errors]
MODULE [MODULE …]
Positional arguments
MODULE
The Python module name. This may be an import path resolvable in the current environment, or a file path to a Python module or package.
Module arguments
-h, — help
show this help message and exit
— version
show program’s version number and exit
-c OPTION=VALUE, — config OPTION=VALUE
Override template options. This is an alternative to using a custom config.mako file in — template-dir. This option can be specified multiple times.
— filter STRING
Comma-separated list of filters. When specified, only identifiers containing the specified string will be shown in the output. Search is case sensitive. Has no effect when — http is set.
-f, — force
Overwrite any existing generated ( — output-dir) files.
— html
When set, the output will be HTML formatted.
When set, the specified modules will be printed to standard output, formatted in Markdown-Extra, compatible with most Markdown-(to-HTML-)to-PDF converters.
-o DIR, — output-dir DIR
The directory to output generated HTML/markdown files to (default: ./html for — html).
— template-dir DIR <
Specify a directory containing Mako templates (html.mako, text.mako, config.mako and/or any templates they include). Alternatively, put your templates in $XDG_CONFIG_HOME/pdoc and pdoc will automatically find them.
— close-stdin
When set, stdin will be closed before importing, to account for ill-behaved modules that block on stdin.
— http HOST:PORT
When set, pdoc will run as an HTTP server providing documentation for specified modules. If you just want to use the default hostname and port (localhost:8080), set the parameter to :.
— skip-errors
Upon unimportable modules, warn instead of raising.
