在使用python中，我們一般在模塊，類，函數下使用docstring添加字符串說明性文檔，使開發人員更好的可以看懂此代碼是做什麽用的。然而寫了那麽多的註釋，我們想要一篇文檔怎麽辦，第一種辦法不可能將寫完的註釋直接手動的ctrl+c ctrl+v的，此時sphinx就出現了，解決了這一問題。

要想使用它，首先得需要安裝它，安裝方式：

pip install sphinx

安裝完成之後，在主項目下創建docs文檔

#創建完docs項目並切換到 docx目錄下
cd docx

在 docx下運行 sphinx-quickstart

之後會提示讓對項目進行一些設置，以生成項目的配置文件，下面是一個推薦的配置：

> Root path for the documentation [.]: doc  # 在當前目錄下新建doc文件夾存放sphinx相關信息
> Separate source and build directories (y/n) [n]:   # 默認，直接回車
> Name prefix for templates and static dir [_]: 
> Project name: python123   # 輸入項目名稱
> Author name(s): 123   # 作者
> Project version: 1.0  # 項目版本
> Project release [1.0]:
> Project language [en]:   # 默認，回車
> Source file suffix [.rst]: 
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y  # 這個很重要，輸入y
> doctest: automatically 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 be 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 the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y  # 很重要，輸入y，表示將源碼也放到文檔中，你看很多python的模塊的文檔，其實都是包含代碼的。
> 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

修改conf.py

import os
import django
import sys
sys.path.insert(0, os.path.abspath(‘..‘))  #註釋掉
sys.path.insert(0, os.path.abspath(‘../..‘)) #更改成這個路徑

修改index.rst 生成文檔都是在index.rst文件下生成，目前測試文件

Welcome to cetc-portraiting‘s documentation!
============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: rest_server.views.basic   # model類.py文件
   :members:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

最後在docs目錄下直接輸入

make html

編譯成功，進入docs目錄，點擊bulid目錄，進入html目錄，查看index.html，就可以看見文檔html了。沒有截生成完的圖片，故看不了實現效果。

python代碼docstring生成文檔之sphinx