python文档生成工具 sphinx 简介
目录
简介
sphinx-build用法
Makefile选项
调用sphinx-apidoc
原文出处
简介
Sphinx是一个工具，她能够轻易地创建智慧和优雅的文档，她是出自Georg Brandl之手，在BSD许可证下授权。
她最初是为了新版的python文档， 因此在python项目的文档具有完美的特性，但是同样支持c/c++，目前正在计划增加对其他的语言的支持。 理所当然，本页面也是使用Sphinx创造自reStructuredText格式源！Sphinx具有如下的特点：
- 输出格式： 超文本标记语言 (包括Windows HTML帮助)，LaTeX (可打印的PDF版本)，手册页，纯文本
- 丰富的交叉引用： 语义标记以及针对函数，类，引用，词汇表（术语）和相似的信息块的自动链接
- 层次结构： 简单的文本树定义，就能自动地链接到同层（兄弟姐妹）、上一层（父母）以及下一层（子女）的文本位置
- 自动生成目录： 通用索引以及语言模块的目录
- 代码高亮： 代码自动高亮，通过使用 Pygments
- 扩展功能： 自动测试的代码片段，包括从Python模块（API文档）的文档字符串
Sphinx 使用 reStructuredText 作为她的标记语言，她的优点大部分是来自于reStructuredText 以及reStructuredText的解析和转换工具（套件）Docutils的强大以及简单明了。
sphinx-build用法
sphinx-build 脚本构建了一个Sphinx文档集。用法如下:
$ sphinx-build [options] sourcedir builddir [filenames]
在这里，sourcedir 是指 源目录，builddir 是指你想指定的生成文档的目录。大部分时候，是不需要指定 filenames。
sphinx-build 脚本有如下的选项:
-b buildername
最重要的选项: 它选择生成器。常见的生成器如下：
html
生成HTML页面。这是默认生成器。
dirhtml
生成HTML页面，但是每个文件单独一个目录。如果web服务器提供服务，能够生成漂亮的URLs(没有 .html 后缀)。
singlehtml
整个内容生成一个HTML页面。
htmlhelp, qthelp, devhelp, epub
生成HTML文件，包含了生成上述格式的文档集合的其他信息。
latex
生成可以被编译成PDF文件的LaTeX源文件通过使用 pdflatex。
man
生成UNIX操作系统的groff格式的手册。
texinfo
生成Texinfo文件，它能够通过 makeinfo 处理成 Info 文件。
text
生成纯文本文件。
gettext
生成gettext的风格的消息目录（.pot 后缀的文件）。
doctest
如果 doctest 激活，执行文件中所有的doctests。
linkcheck
检查所有的外部链接的完整性。
请参看 Available builders，里面列出了Sphinx自身附带的所有的生成器。用户可以添加自己的生成器扩展。
-a
如果给定，总是生成所有输出文件。默认是只生成新的和更改的源文件的输出文件。（这可能并不适用于所有的生成器。）
-E
不要使用已保存的 环境 （系统缓存所有交叉引用），会完全重新生成。默认是仅仅读取和解析自上次运行后新的或者已更新的源文件。
-t tag
定义标签 tag。这跟 only 指令（标识符）关系密切，如果设置标签就会只包含 only 指令（标识符）的内容。
New in version 0.6.
-d path
因为Sphinx在生成输出文件之前，必须读取和解析所有的源文件，被解析过的源文件会被缓存为”doctree pickles”。通常，这些缓存文件会被放入于生成目录中的名为 .doctrees 的文件夹里；使用该选项可以选择不同的缓存文件夹（所有生成器都可以共享doctrees文件夹）。
-c path
使用给定的配置文件目录，忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路径可能会跟配置文件目录有关，所以也必须使用指定的路径。
New in version 0.3.
-C
不使用配置文件；使用 -D 选项后的配置值。
New in version 0.5.
-D setting=value
覆盖配置文件 conf.py 中一个配置值对。该值必须是一个字符串或者字典值。对于字典值，需要给吃键值对类似：-D latex_elements.docclass=scrartcl。对于布尔值，使用 0 或者 1。
Changed in version 0.6: The value can now be a dictionary value.
-A name=value
在HTML模版中，把 value 赋给 name 。
New in version 0.5.
-n
运行在严格模式。目前，这会对所有丢失的引用抛出警告。
-N
禁止带颜色的输出。（Windows下任何的带颜色的输出都是无效的。）
-q
不要在标准输出上输出任何东西，只给出标准错误的警告和错误。
-Q
不要在标准输出上输出任何东西，也包括警告。只有错误被写入标准错误。
-w file
输出除标准错误外的警告（和错误）到指定的文件。
-W
把警告转换成错误输出。这就说构建会在第一个警告的时候停止，sphinx-build 会以错误状态1退出。
-P
（仅调试时有用。）构建时候，如果出现未处理的遗产，运行python调试器，pdb。
在命令行中，你可以在源目录以及生成目录后给出一个或者多个文件名。Sphinx 将会尝试构建给出的这些文件的输出（以及它们的依赖。）
Makefile选项
由 sphinx-quickstart 生成的 Makefile 和 make.bat 文件是只使用了 sphinx-build 的 -b 和 -d 参数。 然而， 它们支持以下的变量（参数）来定制化：
PAPER
latex_paper_size 的值。
SPHINXBUILD
替代 sphinx-build 的命令。
BUILDDIR
指定生成的目录，而不是使用在 sphinx-quickstart 中选择的路径。
SPHINXOPTS
sphinx-build 的附加选项。
调用sphinx-apidoc
sphinx-apidoc 能够对一个python包生成完全的自动的API文档。调用它像这样:
$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
packagedir 是指生成文档的包所在的路径， outputdir 生成的文档所存放的路径。任何给定的 pathnames 是在生成过程中需要忽略的路径名（[pathnames]里的东西在生成文档中是忽略的。）
sphinx-apidoc 有如下些选项:
-o outputdir
给出生成的文档所在的路径。
-f, --force
通常，sphinx-apidoc不会重新生成任何文件。使用这个选项强制重新生成所有的文件。
-n, --dry-run
使用这个选项的话，不会有任何文件生成。（空运行，或者称为干运行。）
-s suffix
这个选项指定了输出的文件的文件名后缀。默认情况下，后缀是 rst。
-d maxdepth
如果存在内容表，设置内容表的最大深度。
-T, --no-toc
这可以防止生成的表的内容文件 modules.rst。但是当 --full 给出的时候，本选项就不起作用了。
-F, --full
此选项使得sphinx-apidoc创建一个完整的Sphinx项目，与 sphinx-quickstart 使用同样的机制。大部分的配置值是设置成默认的值，但是你可以通过如下选项修改一些重要的配置值。
-H project
设置项目名称，使得生成到输出的文件 (请见 project).
-A author
设置作者名，使得生成到输出的文件 (请见 copyright).
-V version
设置项目版本，使得生成到输出的文件 (请见 version).
-R release
设置项目发布，使得生成到输出的文件 (请见 release).
原文出处
www.pythondoc.com/sphinx/index.html
www.pythondoc.com/sphinx/invocation.html
python文档生成工具 sphinx 简介相关推荐
- python自带的文档生成工具,Python文档生成工具pydoc
在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介 ...
- python文档生成工具_pydoc --- 文档生成器和在线帮助系统 — Python 3.9.1rc1 文档
pydoc --- 文档生成器和在线帮助系统¶ The pydoc module automatically generates documentation from Python modules. ...
- python文档生成工具pydoc
为了找到对象及其文档内容,pydoc 会导入文档所在的模块. 因此,任何模块层级的代码都将被执行. 请使用 if name == 'main': 语句来确保一个文件的特定代码仅在作为脚本被发起调用时执 ...
- python doc_Python文档生成工具pydoc使用介绍
在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介 ...
- python文档生成_python文档生成工具：pydoc、sphinx；django如何使用sphinx？
文档生成工具: 自带的pydoc,比较差 建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
- sphinx：基于 Python 的文档生成工具
sphinx:基于 Python 的文档生成工具 Motivation 对于软件开发来说,文档是软件可维护性的重要保障.sphinx 是一款文档生成工具,以 restructuredText 为标记语 ...
- Apiggs —— 非侵入性的 RestDoc 文档生成工具
程序员一直以来都有一个烦恼,只想写代码,不想写文档.代码就表达了我的思想和灵魂. Python提出了一个方案,叫docstring,来试图解决这个问题.即编写代码,同时也能写出文档,保持代码和文档的一 ...
- Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码 然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
- 一款常用文档生成工具：Doxygen
关注+星标公众号,不错过精彩内容 来源 | 简书 编排 | strongerHuang 程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具[Doxygen]生成. 什么是Doxyge ...
最新文章
- 记-php的设计模式
- 利用logminer恢复delete误删除操作的数据
- 【珍藏版】 200个机器学习 NLP Python 免费相关教程
- python游戏设计的课题背景_游戏设计论文开题报告
- 数学老师在成人网站上教微积分，年入百万 。。。
- 【Scratch案例教学】scratch旋转风车 scratch编程案例教学 scratch创意编程 少儿编程教案
- git 小乌龟代码回退
- 如何准备蓝桥杯以及刷题
- 网秦安全盾 原理分析
- wildfly 21中应用程序的部署
- 极光尔沃A6-3d打印机体验
- 自动驾驶汽车测试技术与应用进展
- 盘点2015年手机芯片行业：多极世界来临
- 【计组之EDA】学了EDA，这些元件符号及常用化简公式你都会了叭（超详细图示ai）
- python实现逐步回归_Python怎么做逐步回归？
- 程序员用得到的网站或工具
- 电脑主板资料库 05【转至www.ongood.com.tw】【FreeXploiT收集整理】
- 山东大学软件学院数据结构（考试）——期末考试回忆版
- stm31.js使用详解
- 机器学习之决策树算法（3）