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了。没有截生成完的图片,故看不了实现效果。
python代码docstring生成文档之sphinx的更多相关文章
- Sphinx将python代码注释生成文档
安装 使用pip进行安装: pip install sphinx 初始化 进入你代码所在的目录,输入: sphinx-quickstart 下图:PRD是代码所在目录,生成的文档保存目录设成doc ...
- API Studio 5.1.2 版本更新:加入全局搜索、支持批量测试API测试用例、读取代码注解生成文档支持Github与码云等
最近在EOLINKER的开发任务繁重,许久在博客园没有更新产品动态了,经过这些日子,EOLINKER又有了长足的进步,增加了更多易用的功能,比如加入全局搜索.支持批量测试API测试用例.读取代码注解生 ...
- 使用Sphinx为你的python模块自动生成文档
Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等. 安装 创建一个sphinx项目 下面的命令会 ...
- 【Sphinx】 为Python自动生成文档
sphinx 前言 Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等 开始 建一个存放文档的do ...
- eoLinker 新功能发布,增加了识别代码注释自动生成文档功能
产品地址:https://www.eolinker.com开源代码:https://www.eolinker.com/#/os/download在线生成代码注释工具:http://tool.eolin ...
- JavaScript 定义类的最佳写法——完整支持面向对象(封装、继承、多态),兼容所有浏览器,支持用JSDuck生成文档
作者: zyl910 [TOC] 一.缘由 由于在ES6之前,JavaScript中没有定义类(class)语法.导致大家用各种五花八门的办法来定义类,代码风格不统一.而且对于模拟面向对象的三大支柱& ...
- JavaScript 实现命名空间(namespace)的最佳方案——兼容主流的定义类(class)的方法,兼容所有浏览器,支持用JSDuck生成文档
作者: zyl910 一.缘由 在很多的面向对象编程语言中,我们可以使用命名空间(namespace)来组织代码,避免全局变量污染.命名冲突.遗憾的是,JavaScript中并不提供对命名空间的原生支 ...
- 使用swagger在netcorewebapi项目中自动生成文档
一.背景 随着前后端分离模式大行其道,我们需要将后端接口撰写成文档提供给前端,前端可以查看我们的接口,并测试,提高我们的开发效率,减少无效的沟通.在此情况下,通过代码自动生成文档,这种需求应运而生,s ...
- 使用doctest代码测试和Sphinx自动生成文档
python代码测试并自动生成文档 Tips:两大工具:doctest--单元测试.Sphinx--自动生成文档 1.doctest doctest是python自带的一个模块.doctest有两种使 ...
随机推荐
- IE8 兼容 getElementsByClassName
IE8以下版本没有getElementsByClassName这个方法,以下是兼容写法 function ieGetElementsByClassName() { if (!document.getE ...
- ASP.NET动态网站制作(18)-- jq作业讲解及知识补充
前言:这节课主要讲解js及jq作业,并在作业讲解完后补充关于jQuery的一些知识点. 内容: 1.作业讲解:计算器那一块考虑的各种情况还不算完善,只实现了基本的功能,还需多多练习使用jQuery. ...
- Unity3D研究院之在开始学习拓展编辑器
Unity拥有非常丰富的拓展编辑器接口,如果是在网上下载过别人写的插件,你会发现为什么它的监测面板视图和普通的不一样?其实是他通过代码自己绘制的监测面板,这篇博文MOMO带大家来学习编辑器.如下图所示 ...
- GUN C中的错误报告
在C语言中,很多库函数在调用失败时都会返回特定的值.比如返回-1,空指针,EOF等.但是这些值仅仅表示的调用失败,并未给出详细的错误信息.如果想查看详细的错误内容,就要去查看errno的错误代码,er ...
- 在UIWebView中设置cookie
本文转载至 http://blog.csdn.net/chengyakun11/article/details/8863878 项目中,需要在打开3g网页时,通过cookie传递一些信息. 实现代码 ...
- Spring框架结构
在processOn思维导图上看的一个程序员写的,挺不错的,分享出来,便于学习和回顾.
- 【BZOJ2790】[Poi2012]Distance 筛素数+调和级数
[BZOJ2790][Poi2012]Distance Description 对于两个正整数a.b,这样定义函数d(a,b):每次操作可以选择一个质数p,将a变成a*p或a/p, 如果选择变成a/p ...
- Discrete Function(简单数学题)
Discrete Function There is a discrete function. It is specified for integer arguments from 1 to N (2 ...
- 【python】-- MySQL简介、安装、操作
MySQL简介.安装.操作 数据库(Database)是按照数据结构来组织.存储和管理数据的仓库,每个数据库都有一个或多个不同的API用于创建,访问,管理,搜索和复制所保存的数据.我们也可以将数据存储 ...
- 为什么Git 比 SVN 好
原文链接:http://www.worldhello.net/2012/04/12/why-git-is-better-than-svn.html Why Git is better than SVN ...