Python write automation uses Sphinx to extract Python code docstring

when using Python, a feature is a document string in Python, The document string is also known as docstrings. Use the document string to add descriptive documentation to our modules, classes, and functions, making the program easier to read. This seems to be no different from the annotations in other languages, however, the document strings in Python are special in that Python provides the appropriate method to output these descriptive documents.

Assume the following function:

def Test():    "' | # @function: TEST | # @description: TEST | # # @return Value:none | # # @logic: Test | # # @warning: Test " "    ImportATF.plugin.Desktopcommon  as Desktopcommon    Desktopcommon.stopprocess("Notepad")

we can get the description of the Test () function using test.__doc__, and, by invoking the Help function, the actual contents of the function are also documented. In other words, help (test), the actual output is the test () function of the description of the document.

Sphinx is a third-party tool that extracts documentation from Python code and generates HTML files. Explain how to generate the API documentation for Python code with Sphinx.

The first need to install Sphinx, the installation of a variety of methods, can be installed directly with Easy_install, can also be installed in other ways. After installation, you need to add the Python Scripts directory to the system environment variables, such as c:\\python27\\scripts.

You can now generate the documentation for the Python file.

Let's say our code file is under the D:\\test directory.

(1) Enter the D:\\test directory in the Command Line window and run the Sphinx-quickstart

Sphinx will then prompt for some setup of the project to build the project's configuration file, and here is a recommended configuration:

> RootPath forThe documentation[.]:<ENTER>> separateSource andBuild Directories(y/N) [N]:y> Nameprefix forTemplates andStatic dir[_]:<ENTER>> Projectname:An_example_pypi_project> Authorname(s):Andrew Carter> Projectversion:0.0.1> ProjectRelease[0.0.1]:<ENTER>> Sourcefile suffix[.rst]:<ENTER>> Nameof your master document(without suffix) [Index]:<ENTER>>Autodoc:automatically insert Docstrings fromModules(y/N) [N]:y>doctest:automatically test code snippetsinchdoctest Blocks(y/N) [N]:N>Intersphinx:link betweenSphinxdocumentation of different projects(y/N) [N]:y>Todo:Write"Todo"entries that can shownorHidden on Build(y/N) [N]:N>Coverage:Checks forDocumentation Coverage(y/N) [N]:N>Pngmath:include math,rendered asPNG Images(y/N) [N]:N>Jsmath:include math,renderedinchThe browser byJsmath (y/N) [N]:N>ifconfig:conditional inclusion of content based on config values(y/N) [N]:y> Create Makefile? (Y/N) [y]:N> Create WindowsCommand File? (Y/N) [y]:N

after running, the source folder is generated under the current directory, and the conf.py and Index.rst files are available under the source folder

(2) Modify the conf.py file. The goal is to ensure that the package that contains the Python source code can be found in the system path.

Change Sys.path.insert (0,os.path.abspath (')) to Sys.path.insert (0,os.path.abspath ('. ')) and remove the comment

(3) Generate RST file

Run under command line: Sphinx-apidoc-o OutputDir Packagedir

Where: OutputDir is the directory of source, Packagedir is the directory where the code resides

(4) After generating the RST file, the HTML file can be generated. Go to the source directory and run:

Sphinx-build-b HTML. ./output

The output folder is generated under the source directory, and the generated HTML files are in the output folder.

Python write automation uses Sphinx to extract Python code docstring