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有两种使 ...
随机推荐
- php 模拟get和post提交方法[解决ajax跨域问题]
get: $url = "http://www.111cn.net /index.php?a=b&c=d&e=f&g=" . urlencode('王璐个人 ...
- selenium实现在新窗口打开链接
问题:页面代码中不存在target="_blank",怎么实现点击一个按钮,在新窗口中打开? WebElement link = element.findElement(By.ta ...
- SpringMVC拦截器实现登录认证
项目结构如图: 需要的jar:有springMVC配置需要的jar和jstl需要的jar SpringMVC包的作用说明: aopalliance.jar:这个包是AOP联盟的API包,里面包含了针对 ...
- 牛人blog汇总
1.天一思维: https://blog.csdn.net/tszty1997?t=1
- 九度OJ 1189:还是约瑟夫环 (约瑟夫环)
时间限制:1 秒 内存限制:32 兆 特殊判题:否 提交:820 解决:522 题目描述: 生成一个长度为21的数组,依次存入1到21: 建立一个长度为21的单向链表,将上述数组中的数字依次存入链表每 ...
- What Every Computer Scientist Should Know About Floating-Point Arithmetic
http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html
- The Princess and the Pea,摘自iOS应用Snow White and more stories
Once upon a time there was a prince who wanted to marry a real princess.从前,有个王子想和真正的公主结婚. He looked ...
- monokai-background
foreground-color:f8f8f2 background-color:272822
- 培训笔记——Linux历史
1. 计算机有分时与实时操作系统的区分,如Dos为实时操作系统,你只能给它下达一个命令,这个命令执行完了,你才能下达下一个命令:像Linux和我们用的Windows就是分时操作系统,特点是可以并发 ...
- C# 自定义异常类 throw语句抛出异常
Exception概述: 异常(Exception)一般分为两大类SystemException.ApplicationException,前者是预定义的异常类,后者是用户自定义异常类时需要继承的类 ...