Update API Reference in Documentation

pre-commit hook id: docs-api-reference

Run this hook to update the API Reference section of your documentation.

The hook walks through a package directory, finding all Python files and creating a markdown file matching it along with recreating the Python API tree under the docs/api_reference/ folder.

The hook will run when any Python file is changed in the repository.

The hook expects the documentation to be setup with the MkDocs framework, including the mkdocstrings plugin for parsing in the Python class/function and method doc-strings, as well as the awesome-pages plugin for providing proper titles in the table-of-contents navigation.

Using it together with CI/CD workflows

If this hook is being used together with the workflow CI - Tests, to test if the documentation can be built, or CD - Release and/or CI/CD - New updates to default branch, to build and publish the documentation upon a release or push to the default branch, it is necessary to understand the way the Python API modules are referenced in the markdown files under docs/api_reference/.

By default, the references refer to the Python import path of a module. However, should a package be installed as an editable installation, i.e., using pip install -e, then the relative path from the repository root will be used.

This differentiation is only relevant for repositories, where these two cases are not aligned, such as when the Python package folder is in a nested folder, e.g., src/my_package/.

In order to remedy this, there are a single configuration in each workflow and this hooks that needs to be set to the same value. For this hook, the option name is --relative and the value for using the relative path, i.e., an editable installation, is to simply include this toggle option. If the option is not included, then a non-editable installation is assumed, i.e., the -e option is not used when installing the package, and a proper resolvable Python import statement is used as a link in the API reference markdown files. The latter is the default.

For the workflows, one should set the configuration option relative to true to use the relative path, i.e., an editable installation. And likewise set relative to false if a proper resolvable Python import statement is to be used, without forcing the -e option. The latter is the default.

Expectations

It is required to specify the --package-dir argument at least once through the args key.

Otherwise, as noted above, without the proper framework, the created markdown files will not bring about the desired result in a built documentation.

Options

Any of these options can be given through the args key when defining the hook.

Name	Description	Required	Type	Default
--package-dir	Relative path to a package dir from the repository root, e.g., 'src/my_package'. This input option can be supplied multiple times.	Yes	string
--docs-folder	The folder name for the documentation root folder.	No	string	docs
--unwanted-folder	A folder to avoid including into the Python API reference documentation. If this is not supplied, it will default to __pycache__. Note: Only folder names, not paths, may be included. Note: All folders and their contents with these names will be excluded. This input option can be supplied multiple times.	No	string	__pycache__
--unwanted-file	A file to avoid including into the Python API reference documentation. If this is not supplied, it will default to __init__.py Note: Only full file names, not paths, may be included, i.e., filename + file extension. Note: All files with these names will be excluded. This input option can be supplied multiple times.	No	string	__init__.py
--full-docs-folder	A folder in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. This input option can be supplied multiple times.	No	string
--full-docs-file	A full relative path to a file in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. This input option can be supplied multiple times.	No	string
--special-option	A combination of a relative path to a file and a fully formed mkdocstrings option that should be added to the generated MarkDown file. The combination should be comma-separated. Example: my_module/py_file.py,show_bases:false. Encapsulate the value in double quotation marks (") if including spaces ( ). Important: If multiple package-dir options are supplied, the relative path MUST include/start with the package-dir value, e.g., "my_package/my_module/py_file.py,show_bases: false". This input option can be supplied multiple times. The options will be accumulated for the same file, if given several times.	No	string
--relative	Whether or not to use relative Python import links in the API reference markdown files. See section Using it together with CI/CD workflows above.	No	flag
--debug	Whether or not to print debug statements.	No	flag

Usage example

The following is an example of how an addition of the Update API Reference in Documentation hook into a .pre-commit-config.yaml file may look. It is meant to be complete as is.

repos:
  - repo: https://github.com/SINTEF/ci-cd
    rev: v2.8.0
    hooks:
    - id: docs-api-reference
      args:
      - --package-dir
      - src/my_python_package
      - --package-dir
      - src/my_other_python_package
      - --full-docs-folder
      - models
      - --full-docs-folder
      - data