Automatically generate API documentation from Python source code comments

Wrote a small open source project of screen automatic control
, Need to write documentation, this may be the most painful job for programmers, haha.
In order to reduce the workload as much as possible, it is best to directly generate the API call part with source code comments-so at least you don't have to write it twice, and the comments are closest to the source code, so it is convenient to write against each other.

After exploring the generation tool, I found that it is not that simple. There are currently three mature and available:

1. Pydocs : The python environment comes with it, but it is a bit too simple. You can only specify files/classes/modules one by one to generate documents. The generated content is output to the console by default, and you have to redirect to the file. The advantage is that it natively supports Markdown. . Of course, the other two tools are a bit too complicated, and I did not find a balanced tool like JavaDoc.
2. Sphinx : Old-brand document generation tool. Like the following MkDocs, it is a complete document organization and management tool that can generate Html documents. The full set of documents should be managed as a project. If you want to generate documentation from source comments, you need to install extensions such as autodoc. The biggest disadvantage of Sphinx is that it is awkward to use a document format called reStructuredText (.rst file). For details, see Use Sphinx to automatically generate API documentation for the project
3. MkDocs : A relatively new document management tool that organizes documents in Markdown format. After installing the plug-in Mkdocstrings , it also supports generating md files from source comments. There are also more detailed tutorials . This article mainly supplements the pits that have been stepped on.

First of all, MkDocs manages the document as a project. The markdown file we write is equivalent to the "document source code", which will be "compiled" into Html (supporting multiple styles), and the plug-in Mkdocstrings is from the python source code. Extract comments from the file to generate "document source code" in mk format.

When we first got in touch, we might hesitate: What is the relationship between this project and the original python project? In fact, apart from extracting comments, the two items do not matter. You can safely create a directory in the original python project and use the mkdocs new command to create a new document project.

After creating a new project, mkdocs will generate a configuration file in yaml format in the specified directory, create a new docs directory as the location of the "document source code", and generate a default document named index.md.

In order to support annotation generation documentation, pip needs to install mkdocstrings, then modify the mkdocs.yml configuration file to enable this plugin

plugins:
  - mkdocstrings

Then import the module name of the python source code in a special format in your own md file (or the generated index.md, depending on where you want to generate it), for example:

## generated
::: autopy   # autopy是模块名，可以写多级，比如autopy.core.data这样，前面的三个冒号，表示这里需要调用mkdocstrings来生成

Afterwards, the command line calls mkdocs build to generate the corresponding html file, or calls mkdocs serve start a local http server and preview it through a browser. At this time, an error may be reported: the specified module cannot be found, which is probably caused by the python source code not being added to the system path.

We can of course add the source code path directly to the PATHONPATH environment variable, but this will have the side effects of affecting other programs, and it has to be added according to the absolute path, which is not flexible enough. Fortunately, the mkdocstrings configuration is powerful enough to support dynamic code. At this time, you can add handlers in the mkdocs.yml file:

plugins:
  - mkdocstrings
      handlers:
          python:
            setup_commands:
              - import sys
              - sys.path.insert(0, "..")

This is equivalent to telling mkdocstring, before extracting comments, execute the statement in setup_commands, and add the parent directory through sys.path.insert (we created a new document project in the python source code directory, so for the document project, The source code is the parent directory).

If you execute mkdocs serve again, you will find that in the generated html document, ::: autopy has been replaced by comments in the code.

Note: Mkdocs requires code comments to comply with Google specification .