用Sphinx自动生成python代码注释文档

pip install -U sphinx

安装好了之后,对Python代码的文档,一般使用sphinx-apidoc来自动生成:
查看帮助
mac-abeen:doc_logic abeen$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_path, ...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.

The <exclude_path>s can be files and/or directories that will be excluded
from generation.

Note: By default this script will not overwrite already created files.

Options:
-h, --help show this help message and exit
-o DESTDIR, --output-dir=DESTDIR
Directory to place all output
-d MAXDEPTH, --maxdepth=MAXDEPTH
Maximum depth of submodules to show in the TOC
(default: 4)
-f, --force Overwrite existing files
-l, --follow-links Follow symbolic links. Powerful when combined with
collective.recipe.omelette.
-n, --dry-run Run the script without creating files
-e, --separate Put documentation for each module on its own page
-P, --private Include "_private" modules
-T, --no-toc Don't create a table of contents file
-E, --no-headings Don't create headings for the module/package packages
(e.g. when the docstrings already contain them)
-M, --module-first Put module documentation before submodule
documentation
-s SUFFIX, --suffix=SUFFIX
file suffix (default: rst)
-F, --full Generate a full project with sphinx-quickstart
-H HEADER, --doc-project=HEADER
Project name (default: root module name)
-A AUTHOR, --doc-author=AUTHOR
Project author(s), used when --full is given
-V VERSION, --doc-version=VERSION
Project version, used when --full is given
-R RELEASE, --doc-release=RELEASE
Project release, used when --full is given, defaults
to --doc-version
--version Show version information and exit

生成命令
sphinx-apidoc [options] -o outputdir packagedir [pathnames]
进入outputdir目录
make html
然后就能在\_build\html文件夹中看到生成好的文档了,还支持查找的功能

注意修改conf.py把项目目录加入,否则生成时找不到模块没法导入
sys.path.append(os.path.abspath('/users/abeen/abeen/**/web'))

 示例:

1: 在src(源码目录)目录上级目录下执行

sphinx-apidoc -F -o ./apidoc ./src

在当前目录下新建apidoc目录,生成api文档的文件夹就在此目录下,./src 表示需要生成api文档的目录。

2: 进入apidoc目录 修改conf.py文件 设置代码路径为sys.path.insert(0, os.path.abspath('../src'))
3: 在apidoc目录下执行make html 生成html文件.

 

Sphinx 标记语法示例
This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself. Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles. Lists can be unnumbered like: * Item Foo
* Item Bar Or automatically numbered: #. Item 1
#. Item 2 Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers! 嵌入代码:
  • 行内代码 用``code``
  • 简单代码块 在代码块的上一个段落后面加2个冒号,空一行后开始代码块,代码块要缩进.
  • 复杂代码块 使用code-block指导语句,还可以选择列出行号和高亮重点行等.
source code below ::                                             

    void foo()
{ } source code again .. code-block:: c
:linenos:
:emphasize-lines: , void foo()
{ }

[Dynamic Language] 用Sphinx自动生成python代码注释文档的更多相关文章

  1. 利用graphviz软件和pycallgraph库自动生成Python代码函数调用关系图

    参考博文:https://blog.csdn.net/qq_36408085/article/details/82952846 https://blog.csdn.net/fondax/article ...

  2. 使用sphinx快速生成Python API 文档

    一  简单介绍 不管是开源还是闭源,文档都是很重要的.当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了.所以我们要写文档.大部分情况,我们不希望维护一份代码再加上一份文档, ...

  3. 文件参数化-utp框架之根据yaml文件自动生成python文件+utp运行用例

    根据yaml文件自动生成python文件 utp框架: bin目录:存放执行文件(run.py) cases目录:存放生成的用例的python文件(该目录下的文件为根据data目录下的测试用例生成的p ...

  4. wsdl自动生成Java代码,根据wsdl生成Java代码

    wsdl自动生成Java代码,根据wsdl生成Java代码 >>>>>>>>>>>>>>>>>&g ...

  5. 使用xorm工具,根据数据库自动生成 go 代码

    使用xorm工具,根据数据库自动生成 go 代码 引入 使用 golang 操作数据库的同学都会遇到一个问题 -- 根据数据表结构创建对应的 struct 模型.因为 golang 的使用首字母控制可 ...

  6. mybatis自动生成java代码

    SSM框架没有DB+Record模式,写起来特别费劲,只能用下面的方法勉强凑合. 上图中,*.jar为下载的,src为新建的空白目录,.xml配置如下. <?xml version=" ...

  7. PyCharm配置autopep8,自动格式化Python代码

    1. 关于PEP 8 PEP 8,Style Guide for Python Code,是Python官方推出编码约定,主要是为了保证 Python 编码的风格一致,提高代码的可读性. 官网地址:h ...

  8. 基于数据库的自动化生成工具,自动生成JavaBean、数据库文档、框架代码等(v5.8.8版)

    TableGo v5.8.8版震撼发布,此次版本更新如下:          1.新增两个扩展字段,用于生成自定义模板时使用.          2.自定义模板新增模板目录,可以选择不同分类目录下的模 ...

  9. 使用mybatis-generator工具自动生成mybatis代码

    使用mybatis-generator工具自动生成mybatis代码 步骤如下: 1.引入maven  依赖,在项目pom.xml文件中添加 <plugin> <groupId> ...

随机推荐

  1. struts2项目启动报错。关于jar的问题

    严重: Exception starting filter struts2 Unable to load configuration. - bean - jar:file:/D:/apache-tom ...

  2. Python学习笔记(一)python基础与函数

    1.python基础 1.1输入与输出 输出 用print加上字符串,就可以打印指定的文字或数字 >>> print 'hello, world' hello, world > ...

  3. 打造Linux三流娱乐环境,二流办公环境,一流Java开发环境

    写这篇文章的目的首先是为让自己以后再装linux环境时候,不用再通宵google+百度,做个备忘录,其次,给新入Linux环境的同学分享一点个人经验,再高尚点的动机也算是想做为开源技术的传播布道者.我 ...

  4. DWR实现扫一扫登录功能

    前言 <DWR实现后台推送消息到Web页面>一文中已对DWR作了简介,并列出了集成步骤.本文中再一次使用到DWR,用以实现扫一扫登录功能. 业务场景 web端首页点击"登陆&qu ...

  5. jar包目录下MANIFEST.MF标准格式

    jar包目录格式: |-- com | |-- test.class |-- META-INF | |-- MAINFEST.MF 一个正常的jar包下必有META-INF/MANIFEST.MF清单 ...

  6. Swift:属性观察器

    1.简单介绍 属性观察器监控和响应属性值的变化,每次属性被设置值的时候都会调用属性观察器,甚至新的值和现在的值相同的时候也不例外. 可以为除了延迟存储属性之外的其他存储属性添加属性观察器,也可以通过重 ...

  7. Python之路-jQuery

    参考网址:http://jquery.cuishifeng.cn/ 1.安装环境 2.查找元素 3.操作元素 一.安装环境: 1.我们需要去官网下载jQuery,地址:http://jquery.co ...

  8. 003:Posix IPC的消息队列

    1:与FIFO相比,FIFO要求对一个管道写入之前,必须有进程进行读打开.消息队列则不需要有进行在队列上等待消息的到达. 2:POSIX每次读取总是返回优先级最高的,system V则可以返回任意优先 ...

  9. JDBC代码模板

    import java.sql.Connection; import java.sql.SQLException; import java.util.Properties; import org.ap ...

  10. com.caucho.hessian.io.HessianProtocolException: is unknown code 解决方案

    问题: Cannot access Hessian remote service at [http://....../remote/syllabusService]; nested exception ...