python代码docstring生成文档之sphinx

Posted 2020-11-01 karina梅梅

在使用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了。没有截生成完的图片，故看不了实现效果。