本文将介绍使用 sphinx-quickstart 命令初始化时,如何配置。

虽然,在使用 sphinx-quickstart 时,可以全部使用默认值,但,由于是英文,因此将其翻译为了中文。

另外,本文包含了,大量与Sphinx相关的文档链接,包括安装、配置、语法、生成及 pandoc、生成 chm、rst 创建表格技巧。
相当于索引,方便使用。


安装便不必细说了,详见本文的进阶文档。
需要注意,如果 安装 Python 后没有 pip,即,安装目录/Scripts 下不存在 pip.exe 文件,那么你需要手动安装 pip了。

pip 相当于一个包管理器,与 apt-get、yum、npm、bower等一样。使用简单、便捷。

对了,别忘了,将Python 安装目录及 /Scripts 加入系统环境变量里。

命令行,输入,sphinx-quickstart,你会看到:

Welcome to the Sphinx 1.6.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.

欢迎使用 Sphinx 快速创建工具。
按 回车键,使用默认配置,通常这个默认配置,在括号内已给出。

> Root path for the documentation [.]:
设置文档根路径,默认为当前目录。

> Separate source and build directories (y/n) [n]:
是否分开源代码和生成目录

> Name prefix for templates and static dir [_]:
设置模板和静态目录的名称前缀。

> Project name:
设置项目名称

> Author name(s):
设置作者

> Project version []:
设置项目版本

> Project release [1.0]:
设置发部版本

> Project language [en]:
设置项目语言(简体中文 zh_CN)
其他语言列表为: http://www.sphinx-doc.org/en/stable/config.html#confval-language

> Source file suffix [.rst]:
设置源文件扩展名

> Name of your master document (without suffix) [index]:
设置主(首页)文档名称

> Do you want to use the epub builder (y/n) [n]:
是否使用需要生成为 epub 格式
详见:https://baike.baidu.com/item/ePub/9924958

> autodoc: automatically insert docstrings from modules (y/n) [n]:
是否需要 autodoc 模块
详见:http://zh-sphinx-doc.readthedocs.io/en/latest/invocation.html#invocation-apidoc

> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
是否在 doctest 中测试代码
详见:http://www.sphinx-doc.org/en/stable/ext/doctest.html

> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
是否需要链接到其他项目中的文档
详见:http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]:
是否需要TODO(待办事项)支持
详见:http://www.sphinx-doc.org/en/stable/ext/todo.html

> coverage: checks for documentation coverage (y/n) [n]:
是否检查文件覆盖率
详见:http://www.sphinx-doc.org/en/stable/ext/coverage.html

> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
是否需要数学符号并呈现为PNG或SVG图像
详见:http://www.sphinx-doc.org/en/stable/ext/math.html

> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
是否使用MathJax 插件在浏览器中展示数学符号
详见:http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.mathjax

> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
是否包含基于配置的内容
详见:http://www.sphinx-doc.org/en/stable/ext/ifconfig.html

> viewcode: include links to the source code of documented Python objects (y/n) [n]:
是否需要链接到源代码
详见:http://www.sphinx-doc.org/en/stable/ext/viewcode.html

> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
是否创建 .nojekyll 文件以发布到 GitHub
详见:http://www.sphinx-doc.org/en/stable/ext/githubpages.html

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
是否需要 make 文件(生成后,可以直接使用 make html ,而不是调用 sphinx-build。

> Create Windows command file? (y/n) [y]:
创建 Windows 命令行文件

Creating file .\conf.py.
Creating file .\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where “builder” is one of the supported builders, e.g. html, latex or linkcheck.

至此完成项目(目录)结构创建。
你现在可以编辑 ./index.rst 创建其他文档。
构建文档:
make 输出类型
类型有 html、latex 或 linkcheck
其他输出类型,参见:
http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build

另外,输出类型为,htmlhelp 将允许生成chm格式的文档。前提你需要下载Microsoft HTML Help Workshop,之后,打开生成目录的*.hhp 文件,进行编译即可。

如果不想使用 rst ,你可以使用其他如 makedown 进行编写,使用 pandoc 进行格式转换。

进阶文档

手册

安装和 rst 语法

入门

pandoc 文档转换

CHM

其他

发表评论

电子邮件地址不会被公开。 必填项已用*标注