python代码docstring生成文档之sphinx

时间：2021-10-27 15:56:59

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

相关文章