标签：div 路径 clu trait ima basic port toc value
在使用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了。没有截生成完的图片，故看不了实现效果。
标签：div 路径 clu trait ima basic port toc value
原文地址：https://www.cnblogs.com/niejinmei/p/8918858.html
