python代碼docstring生成文檔之sphinx

在使用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了。沒有截生成完的圖片，故看不了實現效果。