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.

Expectations

It is required to specify the --package-dir argument 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	Default	Type
--package-dir	Relative path to package dir from the repository root, e.g., 'src/my_package'.	Yes		string
--docs-folder	The folder name for the documentation root folder.	No	docs	string
--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	__pycache__	string
--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	__init__.py	string
--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	Empty string	string
--debug	Whether or not to print debug statements.	No	False	boolean

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/CasperWA/ci-cd
    rev: v1
    hooks:
    - id: docs-api-reference
      args:
      - --package-dir
      - my_python_package
      - --full-docs-folder
      - models
      - --full-docs-folder
      - data