How to automatically generate documents using MkDocs in python

Preface

There are many python code annotation styles, and the more mainstream ones include reStructuredText style, numpy style, and Google style.

There are also many tools for automatically generating documents, common ones include:

The Pydocs python environment comes with it and supports MarkDown, but the function is relatively simple;
Sphinx is very popular and supports reStructuredText style annotations by default. To support MarkDown, extension plug-in support is required;
The advantage of MkDocs is that it can support the MarkDown format to organize documents and support Google-style annotations;

For those who are familiar with MarkDown syntax, MkDocs is recommended, which is very convenient to use.

Using MkDocs

environment

python3.9
Installation dependencies

mkdocs==1.6.0
mkdocstrings==0.25.1
mkdocstrings-python==1.10.3
mkdocs-autorefs==1.0.1
mkdocs-material==9.5.24
mkdocs-same-dir==0.1.3

Introduction to use

Remember to install the relevant dependencies in advance.

Project structure

Intercepted part of the display:

├── pykit_tools  # Source Code Directory│   ├── __init__.py
├── docs
│   ├── 
│   ├── 
│   └── 
├── .
├── 
├── 
├── requirements_docs.txt

Configuration File

MkDocs main configuration file

site_name: pykit-tools
repo_url: /SkylerHu/pykit-tools
docs_dir: .

# Configure the topictheme:
  name: readthedocs
  # name: material
  language: zh

#Configuration Document Menunav:
  - front page: 
  - use(Usage): docs/
  - Release Notes: docs/
  - Contributor Guide: docs/

# Plug-in configurationplugins:
  - search  # Built-in plugin, adding a search bar to the title, allowing users to search your document  - same-dir  # plugin mkdocs-same-dir  - autorefs
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          # Configure the path to parse code comments          paths: [pykit_tools]
          options:
            heading_level: 3  # Use the third-level menu, which will be reflected in the docs/document            show_root_heading: true
            show_symbol_type_heading: true
            show_source: false
          selection:
            docstring_style: google

Comment configuration for document generation

In the configuration fileoptionsFor details, please refer tomkdocstrings globallocal-options

Sample configurationdocs/(intercepted part), where:::It is the path of the python module of a specific format, configuration class or function:

#Usage
## Decorator::: 
    options:  # will overwrite global configuration        members:
          - handle_exception
          - time_record

::: 
    options:
        members:
            - method_deco_cache
            - singleton_refresh_regular

Run and build

After executing mkdocs serve, you can access it through http://127.0.0.1:8000/;

Execute mkdocs build --clean to build the site directory to build the site, and you can add the site to the .gitignore file;

The html, js and other files in the site directory can be used to deploy them into document service websites.

deploy

For free and open source deployment, there are generally two options:

Github Pages
- Instructions for posting to GitHub Pages；
- Restrictions: Each user can only create a new pages named according to their account name for free;
Readthedocs website
- supportSphinxandMkDocsTwo ways of deployment;
- Related configuration instructions；
- Free use of open source project documents;
- This method is used to host documents.readthedocsthe subject;

This article usesreadthedocsWebsite hosting, the website can log in with a Github account to synchronize github project information and easily import and generate documents.

Deployment requires dependency on configuration files., The content example is as follows:

version: 2

# The environment required for building a documentbuild:
  os: ubuntu-22.04
  tools:
    python: "3.9"

# Document tool related configurationmkdocs:
  configuration: 

# Installation dependenciespython:
  install:
  - requirements: requirements_docs.txt  # Maintain dependency files in the project by yourself

The specific import steps can be completed based on the synchronized GitHub project list and refer to the guidelines and prompts;

This is the article about how to automatically generate documents using MkDocs in Python. For more related content for python MkDocs, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!