Python code docstring generating document Sphinx

In Python, we typically use docstring to add string explanatory documents under Modules, classes, and functions, making it better for developers to understand what this code does. However, write so many comments, we want a document how to do, the first method can not write the comments directly CTRL + C CTRL + V, at this time Sphinx appeared, solve the problem.

To use it, you need to install it first, and install it as follows:

Pip Install Sphinx

After the installation is complete, create a docs document under the main project

#创建完docs项目并切换到 docx Directory CD docx

Running the Sphinx-quickstart under Docx

You will then be prompted to make some settings for the project to build the project's configuration file, which is a recommended configuration:

> Root path for the documentation [.]: Doc # New doc folder in current directory holds Sphinx related information > separate source and build directories (y/n ) [n]: # default, direct carriage return > name prefix for templates and static dir [_]: > Project name:python123 # Enter project name > Author NA Me (s): 123 # Author > Project version:1.0 # Project version > Projects release [1.0]:> project language [en]: # default, enter > Sou rce file suffix [. rst]: > Name of your master document (without suffix) [index]:> do-want to use the Epub Builde R (y/n) [n]:> autodoc:automatically insert Docstrings from modules (y/n) [n]: Y # This is important, input y> Doctest:automaticall  Y test Code snippets in Doctest blocks (y/n) [n]:> intersphinx:link between Sphinx documentation of different projects (y/n)  [n]:> todo:write "Todo" entries that can is shown or hidden on build (y/n) [n]:> coverage:checks for Documentation Coverage (y/n) [n]:> pngmath:include math, rendered as PNG images (y/n) [n]:> mathjax:include Math, rendered in t He browser by MatHjax (y/n) [n]:> ifconfig:conditional inclusion of content based on config values (y/n) [n]:> Viewcode:include Lin KS to the source code of documented Python objects (y/n) [n]: Y # is important, enter Y, means that the source code is also put into the document, you see a lot of Python module documentation, actually contains the code. > Create Makefile? (y/n) [y]:> Create Windows command file? (y/n) [Y]:

之后会在doc目录下生成如下文件

Docs    Build        doctrees        html    source        _static        _templates        conf.py        index.rst    Make.bat    Makefile

Modify conf.py

Import osimport Djangoimport syssys.path.insert (0, Os.path.abspath (' ... '))  #注释掉sys. Path.insert (0, Os.path.abspath ('.. /..‘)) #更改成这个路径

Modify the Index.rst generated document is generated under the Index.rst file, the current test file

Welcome to Cetc-portraiting ' s documentation!============================================. Toctree:::   maxdepth:2   : caption:contents:.. automodule:: Rest_server.views.basic   # Model class. py file   : Members:indices and tables==================*: Ref: ' Genindex ' *: Ref: ' Modindex ' *: Ref: ' Search '

Finally, enter directly in the Docs directory

Make HTML

Compile successfully, enter the Docs directory, click the Bulid directory, go to the HTML directory, view index.html, you can see the document HTML. No truncation of the finished image, it can not see the implementation effect.

Python code docstring generating document Sphinx