码迷,mamicode.com
首页 > 编程语言 > 详细

python代码docstring生成文档之sphinx

时间:2018-04-23 15:46:14      阅读:304      评论:0      收藏:0      [点我收藏+]

标签: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了。没有截生成完的图片,故看不了实现效果。

python代码docstring生成文档之sphinx

标签:div   路径   clu   trait   ima   basic   port   toc   value   

原文地址:https://www.cnblogs.com/niejinmei/p/8918858.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!