tokenpocket官网安卓app下载|sphinx

Sphinx + Read the Docs 从懵逼到入门 - 知乎

Sphinx + Read the Docs 从懵逼到入门 - 知乎首发于人人都懂物联网切换模式写文章登录/注册Sphinx + Read the Docs 从懵逼到入门阿基米东GetIoT.tech 创办人，Indie Hacker继《GitBook 从懵逼到入门》，时隔两年，终于推出姐妹篇《Read the Docs 从懵逼到入门》。从阅读量来看，笔者已经感受到大家对 GitBook 和 Markdown 写作的关注度，所以决定再给大家介绍一种常见的文档管理方案 —— Sphinx + GitHub + Read the Docs 的文档管理方法。简单来说，就是先用 Sphinx 生成文档，然后用 GitHub 托管文档，再导入到 Read the Docs 生成在线文档。无论是管理技术文档、写书、写笔记，亦或想搭建一个属于你的个人知识库，都是一个不错的选择。那我们现在开始吧！1. 背景知识1.1 ReadtheDocsRead the Docs 是一个基于 Sphinx 的免费文档托管项目。该项目在 2010 年由 Eric Holscher、Bobby Grace 和 Charles Leifer 共同发起。2011年3月，Python 软件基金会曾给 Read the Docs 项目资助 840 美元，作为一年的服务器托管费用。此后，受到越来越多开源社区和开发者的关注，2017年11月，Linux Mint 宣布将所有文档转移到 Read the Docs，目前 Read the Docs 已经托管了超过 90000 份文档。Read the Docs 网站：https://readthedocs.org/1.2 SphinxSphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档，使用 reStructuredText 格式。但随着 Sphinx 项目的逐渐完善，目前已发展成为一个大众可用的框架，很多非 Python 的项目也采用 Sphinx 作为文档写作工具，甚至完全可以用 Sphinx 来写书。Sphinx 是 Python 社区编写和使用的文档构建工具，由 Georg Brandl 在 BSD 许可证下开发，它可以令人轻松的撰写出清晰且优美的文档。除了天然支持 Python 项目以外，Sphinx 对 C/C++ 项目也有很好的支持，并在不断增加对其它开发语言的支持，有需要的小伙伴可以持续关注。Sphinx 网站：http://sphinx-doc.org/Sphinx 使用手册：https://zh-sphinx-doc.readthedocs.io/en/latest/index.htmlSphinx（斯芬克斯）一词源自希腊语 Sphiggein，在古埃及神话中被描述为长有翅膀的怪物，大家熟知的人面狮身像就是 Sphinx 的一种。1.3 reStructuredTextreStructuredText 是一种轻量级标记语言。它是 Python Doc-SIG（Documentation Special Interest Group）的 Docutils 项目的一部分，旨在为 Python 创建一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation（pod）的工具。Docutils 可以从 Python 程序中提取注释和信息，并将它们格式化为各种形式的程序文档。值得注意的是，reStructuredText 是一个单词，不是两个，也不是三个。可以简写为 RST、ReST 或 reST，作为一种用于文本数据的文件格式，通常采用 .rst 作为文件后缀。前面提到，Sphinx 使用 reST 作为标记语言。实际上，reST 与 Markdown 非常相似，都是轻量级标记语言。由于设计初衷不同，reST 的语法更为复杂一些。Markdown 的目标很简单，就是为了更简单地写 HTML，完成 text-to-HTML 的任务。而 reST 的目标是，建立一套标准文本结构化格式用以将文档转化为有用的数据格式（简单来说，就是要实现一套简单、直观、明确、原文本可阅读的，且可以转化为其他格式的文档标记语言）。显然，reST 的目标更大一些。reStructuredText 网站：http://docutils.sf.net/rst.html2. 环境搭建这里以 Ubuntu 为例（其他 Linux 发行版、MacOS 或 Windows 也行），首先安装 Python3、Git、Make 等基础软件。 sudo apt install git

sudo apt install make

sudo apt install python3

sudo apt install python3-pip 然后安装最新版本的 Sphinx 及依赖。 pip3 install -U Sphinx为了完成本示例，还需要安装以下软件包。 pip3 install sphinx-autobuild

pip3 install sphinx_rtd_theme

pip3 install recommonmark

pip3 install sphinx_markdown_tables安装完成后，系统会增加一些 sphinx- 开头的命令。 sphinx-apidoc sphinx-autobuild sphinx-autogen sphinx-build sphinx-quickstart3. 快速开始3.1 创建项目我们以建立 diary 日记文档系统为例，先创建并进入 diary 文件夹（后续所有操作都在该文件夹内）。执行 sphinx-quickstart 构建项目框架，将会出现如下对话窗口。 欢迎使用 Sphinx 3.2.1 快速配置工具。

​

Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).

​

Selected root path: .

​

You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate

"source" and "build" directories within the root path.

> 独立的源文件和构建目录（y/n） [n]: 首先，询问你是否要创建独立的源文件和构建目录。实际上对应两种目录结构，一种是在根路径下创建“_build”目录，另一种是在根路径下创建“source”和“build”两个独立的目录，前者用于存放文档资源，后者用于保存构建生成的各种文件。根据个人喜好选择即可，比如我更倾向于独立目录，因此输入 y。接着，需要输入项目名称、作者等信息。 The project name will occur in several places in the built documentation.

> 项目名称: diary

> 作者名称: Rudy

> 项目发行版本 []: v1然后，可以设置项目的语言，我们这里选择简体中文。 If the documents are to be written in a language other than English,

you can select a language here by its language code. Sphinx will then

translate text that it generates into that language.

​

For a list of supported codes, see

https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.

> 项目语种 [en]: zh_CNOK，项目创建完成！（两种目录结构分别如下）Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。build：生成的文件的输出目录。make.bat：Windows 用命令行。_static：静态文件目录，比如图片等。_templates：模板目录。conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 时选中的那些值，可以自行定义其他的值。index.rst：文档项目起始文件。此时我们在 diary 目录中执行 make html，就会在 build/html 目录生成 html 相关文件。在浏览器中打开 index.html，将会看到如下页面。当然，直接访问 html 文件不是很方便，所以我们借助 sphinx-autobuild 工具启动 HTTP 服务。 sphinx-autobuild source build/html默认启动 8000 端口，在浏览器输入 http://127.0.0.1:8000 。但是看到的页面跟上图一样，那换个主题吧！3.2 修改主题打开 conf.py 文件，找到 html_theme 字段，修改为“classic”主题。 #html_theme = 'alabaster'

html_theme = 'classic'保存！可以看到网页变成这样了Sphinx 为我们提供了好多可选的主题，在 Sphinx Themes 都可以找到。大家最熟悉的应该是 sphinx_rtd_theme 主题，其实我们前面已经安装好了。 html_theme = 'sphinx_rtd_theme'那就用这个主题吧！4. 最佳实践4.1 index.rst 语法受篇幅限制，本文无法详细介绍 reST 语法，具体可查看官方文档 RESTRUCTUREDTEXT 简介，这里主要分析 index.rst 的内容。 .. diary documentation master file, created by

sphinx-quickstart on Sat Oct 10 22:31:33 2020.

You can adapt this file completely to your liking, but it should at least

contain the root `toctree` directive.

​

Welcome to diary's documentation!

=================================

​

.. toctree::

:maxdepth: 2

:caption: Contents:

​

​

​

Indices and tables

==================

​

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`第1-4行由 .. + 空格开头，属于多行评论（类似于注释），不会显示到网页上。第6-7行是标题，reST 的标题需要被双下划线（或单下划线）包裹，并且符号的长度不能小于文本的长度。第9-11行是文档目录树结构的描述，.. toctree:: 声明了一个树状结构（toc 即 Table of Content），:maxdepth: 2 表示目录的级数（页面最多显示两级），:caption: Contents: 用于指定标题文本（可以暂时去掉）。第15-20行是索引标题以及该标题下的三个索引和搜索链接。4.2 《我的日记》我们进入 source 目录，修改 index.rst 文件，将标题改为“我的日记”，并添加一个 about 页面。我的日记

=================================

.. toctree::

:maxdepth: 2

:caption: Contents:

about因此我们需要在 source 目录下新建一个 about.rst 文件，并写下内容： 关于

========

​

这是我的公开日记打开浏览器，输入 http://127.0.0.1:8000，将会看到如下页面。接下来，我们为日记添加一级子目录。先在 source/index.rst 中添加路径信息。 我的日记

=================================

​

.. toctree::

:maxdepth: 2

:caption: Contents:

​

2020/index

about在 source 目录下新建一个名为“2020”的文件夹，在“2020”文件夹中再创建“春、夏、秋、冬”四个文件夹，并且在其中分别创建 contents.rst 文件。最后，别忘了还有要新建一个 index.rst 文件。这一步完成后，2020 目录结构如下： 2020

├── index.rst

├── 春

│ └── contents.rst

├── 冬

│ └── contents.rst

├── 秋

│ └── contents.rst

└── 夏

└── contents.rst在 2020/index.rst 文件中添加如下内容。 2020年

=================================

​

.. toctree::

:maxdepth: 2

​

春/contents

夏/contents

秋/contents

冬/contents以及四个 contents.rst 文件的内容：春/contents.rst 春季

========

​

春眠不觉晓，处处闻啼鸟。夏/contents.rst 夏季

========

​

夏早日初长，南风草木香。秋/contents.rst 秋季

========

​

秋风吹不尽，总是玉关情。冬/contents.rst 冬季

========

​

冬尽今宵促，年开明日长。好啦！打开浏览器看一下吧～好啦，日记就先写到这吧！喜欢的小伙伴可以在 luhuadong/diary 点赞+下载。4.3 支持 Markdown前面我们都是用 reST 语法来操作，但如果我们想用 Markdown 写，或者有大量 Markdown 文档需要迁移怎么办呢？虽然 Sphinx 默认不支持 Markdown 语法，但可以通过 recommonmark 插件来支持。另外，如果需要支持 markdown 的表格语法，还需要安装 sphinx-markdown-tables 插件。这两个插件其实我们前面已经安装好了，现在只需要在 conf.py 配置文件中添加扩展支持即可。 extensions = [

'recommonmark',

'sphinx_markdown_tables'

]我们以“秋”为例，将 rst 文件修改为 md 文件。 cd 秋

mv contents.rst contents.md修改 contents.md 文件，增加一些 Markdown 语法内容： # 秋季

​

秋风吹不尽，总是玉关情。

​

## 二级标题

​

​

### 三级标题

​

​

#### 四级标题

​

​

这是一个**段落**

​

| 作者 | 朝代 | 评分 |

| :--: | :--: | :--: |

| 李白 | 唐 | 100 |

​噔噔！打开浏览器，完美～5. 文档托管5.1 上传 GitHub首先在 GitHub 上创建一个 diary 仓库。在本地 diary 目录中添加 README.md 和 .gitignore 文件，在 .gitignore 文件中写入下面一行。 build/表示不跟踪 build 目录，因为我们后面将使用 Read the Docs 进行文档的构建和托管。接着依次执行如下命令即可。 git init

git add .

git commit -m "first commit"

git branch -M main

git remote add origin git@github.com:luhuadong/diary.git

git push -u origin main5.2 网页托管在 Read the Docs 网站 https://readthedocs.org/ 注册，并绑定 GitHub 账户。点击“Import a Project”导入项目，输入项目名称和仓库地址即可。翻车啦，构建失败！（构建成功的话，可以通过 diary-demo.readthedocs.io 链接访问在线文档）原因是 GitHub 从 2020年10月1日起，把主分支的名称从 master 修改为 main 了，但是 Read the Docs 的构建脚本还没兼容。。。（好吧，你们操作的时候应该修好了）编辑于 2020-10-11 10:00信息技术（IT）​赞同 182​​25 条评论​分享​喜欢​收藏​申请转载​文章被以下专栏收录人人都懂物联网用通俗易懂、案例分析的方式介绍物联网AIoT技术文档收

用Sphinx快速制作文档 - 知乎

用Sphinx快速制作文档 - 知乎首发于WoodenRobot技术杂谈切换模式写文章登录/注册用Sphinx快速制作文档WoodenRobotLife is short, should be fun!个人博客地址：woodenrobot.me简介Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章美观的自动索引: 可自动生成美观的模块索引精确的语法高亮: 基于 Pygments 自动生成语法高亮开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.安装SphinxSphinx为Python语言的一个第三方库。我们需要在终端中输入下列命令进行安装：pip install sphinx创建Sphinx项目创建一个用于存放文档的文件夹，然后在该文件夹路径下运行下列命令快速生成Sphinx项目：sphinx-quickstart接下来会让你选择一些配置：1. 设置文档的根路径（回车，使用默认设置）Enter the root path for documentation.

> Root path for the documentation [.]:2. 是否分离source和build目录（输入y,选择分离，方便管理）You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate

"source" and "build" directories within the root path.

> Separate source and build directories (y/n) [n]:3. 设定模板前缀（回车，使用默认选项）Inside the root directory, two more directories will be created; "_templates"

for custom HTML templates and "_static" for custom stylesheets and other static

files. You can enter another prefix (such as ".") to replace the underscore.

> Name prefix for templates and static dir [_]:4. 输入项目名称和作者The project name will occur in several places in the built documentation.

> Project name: Sphinx-test

> Author name(s): test5. 输入项目版本号Sphinx has the notion of a "version" and a "release" for the

software. Each version can have multiple releases. For example, for

Python the version is something like 2.5 or 3.0, while the release is

something like 2.5.1 or 3.0a1. If you don't need this dual structure,

just set both to the same value.

> Project version []: 1.0.0

> Project release [1.0.0]:6. 文档语言（回车，默认即可）If the documents are to be written in a language other than English,

you can select a language here by its language code. Sphinx will then

translate text that it generates into that language.

For a list of supported codes, see

http://sphinx-doc.org/config.html#confval-language.

> Project language [en]:7. 设定文档文就按的后缀The file name suffix for source files. Commonly, this is either ".txt"

or ".rst". Only files with this suffix are considered documents.

> Source file suffix [.rst]:8. 设定首页名称（回车，选择默认index即可）One document is special in that it is considered the top node of the

"contents tree", that is, it is the root of the hierarchical structure

of the documents. Normally, this is "index", but if your "index"

document is a custom template, you can also set this to another filename.

> Name of your master document (without suffix) [index]:9. 根据需要选择是否开启epub输出(一般用不到，回车默认不开启即可)Sphinx can also add configuration for epub output:

> Do you want to use the epub builder (y/n) [n]:10. 根据需求选择是否开启相应的Sphinx拓展功能Please indicate if you want to use one of the following Sphinx extensions:

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y

> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y

> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y

> coverage: checks for documentation coverage (y/n) [n]: y

> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y

> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

Note: imgmath and mathjax cannot be enabled at the same time.

imgmath has been deselected.

> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y

> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n11. 创建项目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]: y

> Create Windows command file? (y/n) [y]: y

Creating file ./conf.py.

Creating file ./index.rst,.md.

Creating file ./Makefile.

Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst,.md 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.项目创建以后目录结构如下所示:.

├── Makefile

├── build

├── make.bat

└── source

├── _static

├── _templates

├── conf.py

└── index.rstbuild:用来存放通过make html生成文档网页文件的目录source：存放用于生成文档的源文件conf.py: Sphinx的配置文件index.rst: 主文档定义文档结构主文档index.rst的主要功能是被转换成欢迎页, 它包含一个目录表（ “table of contents tree”或者 toctree ). Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.toctree指令初始值如下：.. toctree::

:maxdepth: 2你可以在 content 的位置添加文档列表:.. toctree::

:maxdepth: 2

tutorial.md

...注：文档文件放在与index.rst同级目录下。支持markdown文件、更改文档主题Spinx本身不支持.md文件生成文档，需要我们使用第三方库recommonmark进行转换。 首先分别运行下列命令安装recommonmark与sphinx_rtd_theme库。pip install recommonmark

pip install sphinx_rtd_theme安装好，在conf.py中修改下列两个配置：source_suffix = ['.rst', '.md', '.MD']

html_theme = 'sphinx_rtd_theme'并新增：source_parsers = {

'.md': CommonMarkParser,

'.MD': CommonMarkParser,

}生成文档在Sphinx项目所在的文件夹路径下运行下列命令生成文档：make html生成后的文档位于build/html文件夹内，用浏览器打开index.html即可看到生成后的文档。参考文章1. Sphinx 使用手册使用 2. sphinx 制作简洁而又美观的文档3. 使用Sphinx制作说明文档编辑于 2017-07-16 16:33Sphinx（检索引擎）PythonPython 文档​赞同 28​​3 条评论​分享​喜欢​收藏​申请转载​文章被以下专栏收录WoodenRobot技术杂谈木制 robot 呓语

Sphinx使用指南 - 知乎

Sphinx使用指南 - 知乎切换模式写文章登录/注册Sphinx使用指南大海星本文介绍 win10 + ubuntu on win 下如何使用Sphinx。1. 写在前面文中使用的Sphinx的版本信息如下：➜ Pictures sphinx-build --version

sphinx-build 3.2.12. 安装Sphinx和Pandoc2.1 安装 Sphinx安装手册安装 python3安装 pip3打开windows终端win+r 安装 Sphinx pip install -U sphinx - 将sphinx的路径添加到系统PATH中 - 验证是否安装成功 sphinx-build --version 2.2 安装 Pandoc安装手册3. 个人文档 本节中用到的代码示例存放在这里: sphinx-doc-guide 3.1 创建目录并进入mkdir sphinx-doc-guide && cd sphinx-doc-guide3.2 初始化文档➜ sphinx-doc-guide sphinx-quickstart

欢迎使用 Sphinx 3.2.1 快速配置工具。

Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate

"source" and "build" directories within the root path.

> 独立的源文件和构建目录（y/n） [n]: y

The project name will occur in several places in the built documentation.

> 项目名称: sphinx-doc-guide

> 作者名称: double12gzh

> 项目发行版本 []: v1.0

If the documents are to be written in a language other than English,

you can select a language here by its language code. Sphinx will then

translate text that it generates into that language.

For a list of supported codes, see

https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.

> 项目语种 [en]: zh

创建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/conf.py。

创建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/index.rst。

创建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/Makefile。

创建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/make.bat。

完成：已创建初始目录结构。

You should now populate your master file /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/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.3.3 查看文档结构➜ sphinx-doc-guide tree

.

├── build

├── make.bat

├── Makefile

└── source

├── conf.py

├── index.rst

├── _static

└── _templates

4 directories, 4 files 说明： buid这个目录是每次执行make html自动生成的，可以删除添加.gitignore，忽略build3.4 定制conf.py根据自己项目提供的信息将sphinx-doc-guide进行替换。➜ source grep -rin "sphinx-doc-guide" ./

./conf.py:54:project = u'sphinx-doc-guide'

./conf.py:232: (master_doc, 'sphinx-doc-guide.tex', u'sphinx-doc-guide.Documentation',

./conf.py:262: (master_doc, 'sphinx-doc-guide', u'sphinx-doc-guide中文文档',

./conf.py:276: (master_doc, 'sphinx-doc-guide', u'sphinx-doc-guide文档',

./conf.py:277: author, 'sphinx-doc-guide', 'One line description of project.',

./conf.py:295: app.add_config_value('sphinx-doc-guide_config', {根据项目情况修改以下信息：➜ source grep -rin "double12gzh" ./

./conf.py:55:copyright = u'2020, double12gzh'

./conf.py:56:author = u'double12gzh'

./conf.py:233: u'double12gzh', 'manual'),3.5 修改favicon.icoico文件的路径为：sphinx-doc-guide/source/_static/img/favicon.ico3.6 根据需要写组织文档 可以参考本例进行组织 3.7 生成线下预览➜ sphinx-doc-guide make html

正在运行 Sphinx v3.2.1

正在加载翻译 [zh]... 完成

创建输出目录... 完成

构建 [mo]： 0 个 po 文件的目标文件已过期

构建 [html]： 15 个源文件的目标文件已过期

更新环境: [新配置] 已添加 15，0 已更改，0 已移除

阅读源... [ 6%] 0-root /root/anaconda3/lib/python3.7/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document

warn("Container node skipped: type={0}".format(mdnode.t))

阅读源... [ 13%] index 阅读源... [ 20%] makefile/0-mk 阅读源... [ 26%] makefile/1/0-introduction 阅读源... [ 33%] makefile/1/index 阅读源... [ 40%] makefile/2/1-mk 阅读源... [ 46%] makefile/2/2-mk 阅读源... [ 53%] makefile/2/index 阅读源... [ 60%] makefile/3-pic 阅读源... [ 66%] makefile/index 阅读源... [ 73%] python/0-py 阅读源... [ 80%] python/1-py 阅读源... [ 86%] python/11 阅读源... [ 93%] python/2 阅读源... [100%] python/index

查找当前已过期的文件... 没有找到

pickling环境... 完成

检查一致性... 完成

准备文件... 完成

写入输出... [ 6%] 0-root 写入输出... [ 13%] index 写入输出... [ 20%] makefile/0-mk 写入输出... [ 26%] makefile/1/0-introduction 写入输出... [ 33%] makefile/1/index 写入输出... [ 40%] makefile/2/1-mk 写入输出... [ 46%] makefile/2/2-mk 写入输出... [ 53%] makefile/2/index 写入输出... [ 60%] makefile/3-pic 写入输出... [ 66%] makefile/index 写入输出... [ 73%] python/0-py 写入输出... [ 80%] python/1-py 写入输出... [ 86%] python/11 写入输出... [ 93%] python/2 写入输出... [100%] python/index

generating indices... genindex完成

writing additional pages... search完成

复制静态文件... ... 完成

copying extra files... 完成

dumping search index in Chinese (code: zh)... 完成

dumping object inventory... 完成

构建 成功.

HTML 页面保存在 build/html 目录。 生成的文件位于项目根目录的build中。 如果需要清除生成的文件可使用make clean4. 个人博客请参考gzh5. github与readthedocs联动5.1 注册readthedocs帐号地址5.2 导入项目6. 总结 文章中完成的文档托管的页面为sphinx-doc-guide 博客页面为gzh 编辑于 2020-09-20 09:52Sphinx（文档生成器）readthedocspandoc​赞同 2​​添加评论​分享​喜欢​收藏​申请

1. sphinx的安装与使用 — [野火]sphinx文档规范与模版 文档

1. sphinx的安装与使用 — [野火]sphinx文档规范与模版 文档

[野火]sphinx文档规范与模版

latest

为什么使用sphinx写文档

关于本项目

关于野火

快速参与本项目（提交bug或文档修改）

TODO和悬赏任务

使用sphinx和vscode编写文档

1. sphinx的安装与使用

2. 使用vscode编写rst文件

3. docx批量转rst方法

reST语法

1. ReST基础语法

2. 超链接与文件引用

3. 代码高亮

4. 图片与视频

5. 数学符号和公式

6. 特殊提示

7. rst的指令和角色（directive and role）

8. 野火sphinx文档规范

使用markdown

1. 使sphinx支持markdown

2. Markdown示例

文档格式转换

使用pandoc进行文档转换

常见问题

常见问题

版权

版权说明

[野火]sphinx文档规范与模版

Docs »

1. sphinx的安装与使用

Edit on GitHub

1. sphinx的安装与使用¶

1.1. 安装sphinx¶

sphinx官方安装说明：

http://www.sphinx-doc.org/en/master/usage/installation.html

readthedoc官方说明：

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

总的来说步骤如下：

安装python3

通过python3安装sphinx包

根据项目要求安装项目的requirements.txt里的软件包

1.1.1. 安装python3¶

windows直接到python官网下载安装

Ubuntu下使用如下指令安装：

sudo apt install python3

1.1.2. 安装sphinx¶

windows下使用如下指令安装：

py -3 -m pip install sphinx

#国内用户推荐使用清华源安装，使用-i指定源

py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

Ubuntu下使用如下指令安装

python3 -m pip install sphinx

#国内用户推荐使用清华源安装，使用-i指定源

python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

#Ubuntu下可能还需要安装如下软件包

apt-get install python3-sphinx

1.2. 使用模板创建sphinx文档¶

本项目的sphinx已适配好支持markdown、默认的readthedoc主题等内容。

如果是要编写新的书籍，推荐直接使用本项目文档作为模版，修改conf.py文件的配置即可改变项目的名字、主题之类的内容。

1.2.1. 下载项目源码¶

先从github下载本项目源代码：

git clone git@github.com:Embdefire/ebf_contribute_guide.git

下载完成后，可看到本项目的结构大致如下：

├── README 说明文档或软链接至documentation中的说明，方便github阅读

├── base_code 配套代码

└── documentation 配套文档

├── faq 存储常见问题的文档

├── about_us.rst 关于我们

├── _build 文档编译输出目录

├── conf.py sphinx配置文件

├── contribute 如何参与项目，贡献与投稿的说明

├── foreword.rst 前言

├── index.rst 目录

├── make.bat

├── Makefile

├── media 文档中使用的图片文件

├── requirements.txt 文档的python依赖

├── _static

├── _templates

├── TODO.rst 待完成的内容，发布的任务列表

特别内容说明如下：

base_code ：该目录通常存放项目的代码，

documentation ：该目录通常存放项目的文档内容，如我们的rst、markdown文档。

1.2.2. 安装python依赖包¶

使用时，要先根据项目的 documentation/requirements.txt 安装依赖的python包。

#切换至requirements.txt文件的同级目录

cd documentation

#requirements.txt文件的同级目录下执行后面的命令

#Windows指令，推荐使用powershell运行

py -3 -m pip install -r requirements.txt

#Ubuntu指令

python3 -m pip install -r requirements.txt

#国内用户推荐使用清华源安装

#Windows指令，推荐使用powershell运行

py -3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

#Ubuntu指令

python3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

1.2.3. 编写文档¶

安装好后，在项目的文档目录中添加rst或markdown文件即可，

建议使用vs code来编写文档，它非常方便预览文档，

可参考《 使用vscode编写rst文件》来搭建vscode预览sphinx文档的环境。

编写文档时的语法和规范可参考以下内容：

《 ReST基础语法》

《 野火sphinx文档规范》

《 Markdown示例》

1.3. 编译文档¶

如果使用了vscode的rst插件，可以直接保存rst文件后它会自动编译并可预览。

也可以手动编译，到文档源码所在的makefile目录，执行如下命令：

#在文档的makefile目录下执行

#Windows指令

make.bat html

#Ubuntu指令

make html

在设定的build或_build的html目录下会生成静态的html文件。可直接使用这些静态的html文件制作网站。

1.4. 在本地预览文档¶

vscode插件预览有时不够完整，可以在本地开启一个python服务器来预览。

进入到生成的_build/html目录，运行如下指令：

#在生成的html目录执行如下指令

#Windows

py -3 -m http.server 8000

#Ubuntu

python3 -m http.server 8000

运行指令后，在浏览器中打开 http://localhost:8000 即可查看生成的静态网页。

1.5. 允许其它主机预览文档¶

类似地，若要允许其它主机访问自己的文档，执行如下命令即可

#在生成的html目录执行如下指令

#Windows

py -3 -m http.server --bind 0.0.0.0 8000

#Ubuntu

python3 -m http.server --bind 0.0.0.0 8000

运行指令后，在浏览器中打开 http://主机IP:8000 即可查看生成的静态网页。

1.6. 清除编译输出¶

有时html文件不会完全达到我们修改rst后的效果，这可能是因为之前的旧文件影响，

这时可以先清除编译输出再重新编译。

#清除编译输出

#Windows指令

make.bat clean

#Ubuntu指令

make clean

#重新编译

#Windows指令

make.bat html

#Ubuntu指令

make html

1.7. 创建全新的sphinx文档¶

若不想使用本工程模版，可以使用如下指令创建全新的文档。

sphinx-quickstart

按照提示回答问题即可。

推荐使用默认的_build目录，与vscode保持一致。

其中提示语言时可以使用这个中文代码：zh_CN

sphinx默认不支持markdown语法，要支持的话请参考本模版的conf.py文件配置。

Next

Previous

© Copyright 2019, embedfire-野火 www.embedfire.com

Revision 4187bff9.

Built with Sphinx using a theme provided by Read the Docs.

Read the Docs

v: latest

Versions

latest

stable

Downloads

pdf

html

epub

On Read the Docs

Project Home

Builds

Free document hosting provided by Read the Docs.

Welcome — Sphinx documentation

Welcome — Sphinx documentation

Sphinx

Navigation

Documentation »

Welcome

On this page

Welcome

Get started

User Guides

Community guide

Reference guide

Site navigation

Get started

Getting Started

Installing Sphinx

Tutorial: Build your first project

User Guides

Using Sphinx

Writing Sphinx Extensions

LaTeX customization

Sphinx Extensions API

Community

Get support

Contribute to Sphinx

Sphinx FAQ

Sphinx authors

Reference

Command-Line Tools

Configuration

Extensions

reStructuredText

Glossary

Changelog

Projects using Sphinx

Welcome¶

Sphinx makes it easy to create intelligent and beautiful documentation.

Here are some of Sphinx’s major features:

Output formats: HTML (including Windows HTML Help), LaTeX (for printable

PDF versions), ePub, Texinfo, manual pages, plain text

Extensive cross-references: semantic markup and automatic links for

functions, classes, citations, glossary terms and similar pieces of

information

Hierarchical structure: easy definition of a document tree, with automatic

links to siblings, parents and children

Automatic indices: general index as well as a language-specific module

indices

Code handling: automatic highlighting using the Pygments highlighter

Extensions: automatic testing of code snippets, inclusion of docstrings

from Python modules (API docs) via built-in extensions, and much more functionality via third-party

extensions.

Themes: modify the look and feel of outputs via creating themes, and reuse many third-party themes.

Contributed extensions: dozens of extensions contributed by users; most of them installable from PyPI.

Sphinx uses the reStructuredText markup language by default, and can read

MyST markdown via third-party extensions. Both of these

are powerful and straightforward to use, and have functionality

for complex documentation and publishing workflows. They both build upon

Docutils to parse and write documents.

See below for how to navigate Sphinx’s documentation.

See also

The Sphinx documentation Table of Contents has

a full list of this site’s pages.

Get started¶

These sections cover the basics of getting started with Sphinx, including

creating and building your own documentation from scratch.

Get started

Getting Started

Setting up the documentation sources

Defining document structure

Adding content

Running the build

Documenting objects

Basic configuration

Autodoc

Intersphinx

More topics to be covered

Installing Sphinx

Overview

Linux

macOS

Windows

Installation from PyPI

Docker

Installation from source

Tutorial: Build your first project

Getting started

First steps to document your project using Sphinx

More Sphinx customization

Narrative documentation in Sphinx

Describing code in Sphinx

Automatic documentation generation from code

Appendix: Deploying a Sphinx project online

Where to go from here

User Guides¶

These sections cover various topics in using and extending Sphinx for various

use-cases. They are a comprehensive guide to using Sphinx in many contexts and

assume more knowledge of Sphinx. If you are new to Sphinx, we recommend

starting with Get started.

User Guides

Using Sphinx

reStructuredText

Markdown

Cross-referencing syntax

Configuration

Builders

Domains

Extensions

HTML Theming

Internationalization

Sphinx Web Support

Writing Sphinx Extensions

Developing extensions overview

Extension tutorials

Configuring builders

Templating

HTML theme development

LaTeX customization

The latex_elements configuration setting

The sphinxsetup configuration setting

Additional CSS-like 'sphinxsetup' keys

LaTeX macros and environments

Sphinx Extensions API

Important objects

Build Phases

Extension metadata

APIs used for writing extensions

Community guide¶

Sphinx is community supported and welcomes contributions from anybody.

The sections below should help you get started joining the Sphinx community

as well as contributing.

See the Sphinx contributors’ guide if you would

like to contribute to the project.

Community

Get support

Contribute to Sphinx

Contributing to Sphinx

Sphinx’s release process

Organization of the Sphinx project

Sphinx Code of Conduct

Sphinx FAQ

How do I…

Using Sphinx with…

Sphinx vs. Docutils

Epub info

Texinfo info

Sphinx authors

Maintainers

Contributors

Former maintainers

Reference guide¶

Reference documentation is more complete and programmatic in nature, it is a

collection of information that can be quickly referenced. If you would like

usecase-driven documentation, see Get started or User Guides.

Reference

Command-Line Tools

Core Applications

Additional Applications

Configuration

Project information

General configuration

Options for internationalization

Options for Math

Options for HTML output

Options for Single HTML output

Options for HTML help output

Options for Apple Help output

Options for epub output

Options for LaTeX output

Options for text output

Options for manual page output

Options for Texinfo output

Options for QtHelp output

Options for the linkcheck builder

Options for the XML builder

Options for the C domain

Options for the C++ domain

Options for the Python domain

Options for the Javascript domain

Example of configuration file

Extensions

Built-in extensions

Third-party extensions

reStructuredText

reStructuredText Primer

Roles

Directives

Field Lists

Glossary

Changelog

Projects using Sphinx

Documentation using the alabaster theme

Documentation using the classic theme

Documentation using the sphinxdoc theme

Documentation using the nature theme

Documentation using another builtin theme

Documentation using sphinx_rtd_theme

Documentation using sphinx_bootstrap_theme

Documentation using pydata_sphinx_theme

Documentation using a custom theme or integrated in a website

Homepages and other non-documentation sites

Books produced using Sphinx

Theses produced using Sphinx

Projects integrating Sphinx functionality

© Copyright 2007-2024, the Sphinx developers.

Created using Sphinx 7.3.0.

译者前言 — Sphinx 使用手册

译者前言 — Sphinx 使用手册

Sphinx 使用手册

译者前言

«  Sphinx 文档目录

  ::  

Contents

  ::  

引言  »

译者前言

sphinx使用手册,源文档地址 Sphinx .

用户评价:

值得欢呼的好工具，确实方便那些需要书写文档的程序员们!

欢迎

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发.

新版的Python文档 就是由Sphinx生成的，

并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.

本站当然也是使用 Sphinx 生成的，它采用reStructuredText!

Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本

完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息

明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章

美观的自动索引: 可自动生成美观的模块索引

精确的语法高亮: 基于 Pygments 自动生成语法高亮

开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

Sphinx 使用 reStructuredText

作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.

«  Sphinx 文档目录

  ::  

Contents

  ::  

引言  »

© Copyright .

Created using Sphinx 1.5.3.

Sphinx初尝 — Sphinx 使用手册

Sphinx初尝 — Sphinx 使用手册

Sphinx 使用手册

Sphinx初尝

«  引言

  ::  

Contents

  ::  

调用 sphinx-build  »

Sphinx初尝

此文档是Sphinx使用的综览性教程，包含Sphinx常用的任务处理.

绿色箭头链接了任务操作的详细信息.

配置文档源

文档集的根目录叫 source directory. 该目录也包含了 Sphinx 的配置文件 conf.py, 在这里你可以配置Sphinx各个方面，使Sphinx按照你的要求读取源文件并创建文档. [1]

Sphinx 有个脚本叫做 sphinx-quickstart ,它可以帮你建立源目录及默认配置文件 conf.py ，它通过几个简单的问题获取一些有用的配置值.

你仅需要运行

$ sphinx-quickstart

然后回答这些问题. (其中”autodoc” 扩展选项请选中.)

它也会自动匹配 “API 文档” 生成器 sphinx-apidoc; 详细信息请参考 调用 sphinx-apidoc.

定义文档结构

假定你已经运行了 sphinx-quickstart . 它创建了源目录，包含 conf.py

及一份主文档 index.rst (如果你接受了默认选项).主文档 master document 的主要功能是被

转换成欢迎页, 它包含一个目录表（ “table of contents tree”或者 toctree ). Sphinx 主要功能是使用

reStructuredText, 把许多文件组织成一份结构合理的文档.

reStructuredText 导读

toctree 是 reStructuredText的 directive （指令）, 一种用途十分广泛的块标记. 定义了参数、选项及目录.

Arguments 直接在双冒号后面给出指令的名字. 每个指令都有不定个数的参数.

Options 在参数后以”字段列表”的形式给出. 如

maxdepth 是 toctree 指令的选项之一.

Content 具体内容,在选项或参数的后面，隔开一个空行. 每个指令后面都跟着不同作用的内容.

共同的约定是 内容与选项一般有相同的缩进 .

toctree 指令初始为空, 如下:

.. toctree::

:maxdepth: 2

你可以在 content 的位置添加文档列表:

.. toctree::

:maxdepth: 2

intro

tutorial

...

以上精确展示toctree 与文档的转换. 所有的文档以文件名 document names的形式给出,

不需文件后缀名;使用斜线作为目录分隔符.

更多信息请查看 the toctree directive.

现在可以创建toctree指令后的文件及目录了，

它们的章节标题被插入到toctree指令的位置 (与 “maxdepth” 同一缩进) . 现在Sphinx已知道文档的分层结构.

(toctree指令后的文件也可以有 toctree 指令, 会生成更深的层次结构.)

添加内容

在Sphinx源文件里, 可以使用reStructuredText的很多特性.

也有些特性被添加到Sphinx中. 例如, 可以引用参考文件链接 (对所有输出类型均有效) ，使用 ref 角色.

又如, 浏览HTML版本时想要查看文档的源文件，只需点击边框栏的”显示源代码”.

reStructuredText 简介 详细介绍了reStructuredText

Sphinx标记的组成 列出了Sphinx添加的全部标记.

运行创建工具

现在已经添加了一些文件,下面可以创建文档了.

创建工具 sphinx-build , 使用方式

$ sphinx-build -b html sourcedir builddir

sourcedir 是源目录 source directory , builddir 则是放置生成的文档的根目录. -b 是创建工具的选项;这个例子创建HTML文件.

调用 sphinx-build 列出工具 sphinx-build

支持的所有选项.

而且, sphinx-quickstart 脚本创建的 Makefile 和

make.bat 使操作更容易，仅需运行

$ make html

创建 HTML 在设定好的目录里. 执行 make 将不需要任何参数.

怎样产生PDF 文档?

make latexpdf 运行在 LaTeX builder ,点击可以获取pdfTeX工具链.

文档对象

Sphinx的对象 objects (一般含义）在任何 domain （主域）里是指简单的文档. 一个主域包含所有的对象类型,

完整的生成标记或引用对象的描述.

最著名的主域是Python 主域. Python文档建立函数 enumerate() , 在源文件里添加:

.. py:function:: enumerate(sequence[, start=0])

返回一个迭代器，输出包含索引及*sequence*里所有条目的元组.

返回形式为:

enumerate(sequence[, start=0])

返回一个迭代器，输出包含索引及*sequence*里所有条目的元组

指令的参数是对象的描述标示 signature , 内容是对它的说明.同一行可以写多个参数.

Python 主域通常是默认的, 因此不需要特别标记出主域的名字:

.. function:: enumerate(sequence[, start=0])

...

以上在默认主域配置下效果是等同的.

对不同的Python 对象有不同的指令,

如 py:class 或者 py:method . 不同的对象类型有不同的引用角色 role .

这个标记将创建链接到文档的 enumerate()

这个 :py:func:`enumerate` 函数用于 ...

这是一个实例: 可链接 enumerate() .

同样如果默认为 Python 主域 py: 可以省略. 但这不重要，Sphinx会自动发现包含 enumerate() 的文件并且链接.

不同主域对于不同标示有特定的角色，以使输出格式更美观，在C/C++

主域里增加了链接到元素类型的角色.

Sphinx Domains 列出所有主域及其指令/角色.

基本配置

前面提到的文件 conf.py ，控制着Sphinx怎样生成文档.

这个文件以Python 源文件的形式执行你的配置信息 .

高级的使用者则通过Sphinx使其执行, 可以配置它实现不平凡的任务, 例如继承 sys.path 或者导入

模块标示文档的版本.

仅需要修改 conf.py ,可以改变默认值, 删除一些符号，修改对应的值.

(通过标准的 Python 操作符: # 为注释行).或者通过 sphinx-quickstart 初始化一些值.

自定义的配置一般不会由 sphinx-quickstart 自动产生,需要自己添加标记.

记住此文件使用Python 的操作符及字符串、数字、列表等.这个文件默认保存为UTF-8编码, 首行需要添加编码声明.

插入非ASCII字符, 则需要使用Python Unicode 字符串 (如 project = u'Exposé' ).

详情查看 The build configuration file .

自动文档

Python 源代码的文档字符串一般放置了许多的说明信息. Sphinx 支持自动摄取这些说明信息,

使用 “autodoc”的扩展 extension (标准的Python模块扩展,为Sphinx提供的附加功能).

使用autodoc, 需在配置里激活，在 conf.py 放入字符串 'sphinx.ext.autodoc'

位置在 :confval:`extensions` 配置值列表. 现在已配置了一些附加指令.

如,文档化函数 io.open() ,读取源码的标示及文档字符串,这样写:

.. autofunction:: io.open

也可以读取整个类或模块, 使用选项

.. automodule:: io

:members:

autodoc 需要导入到你的模块以便索取文档字符串.

因此,在 conf.py 需要为 sys.path 添加合适的路径.

详情请参考 sphinx.ext.autodoc .

其他话题

其他扩展 (math, intersphinx, viewcode, doctest)

静态文件

选择主题

模板

使用扩展

写扩展

尾注

[1]这只是一般情况. conf.py 可以被移动到其他目录，请参考 configuration directory 及 调用 sphinx-build .

«  引言

  ::  

Contents

  ::  

调用 sphinx-build  »

© Copyright .

Created using Sphinx 1.5.3.

Getting Started — Sphinx documentation

Getting Started — Sphinx documentation

Sphinx

Navigation

Documentation »

Getting Started

On this page

Getting Started

Setting up the documentation sources

Defining document structure

Adding content

Running the build

Documenting objects

enumerate()

Basic configuration

Autodoc

Intersphinx

More topics to be covered

Site navigation

Get started

Getting Started

Installing Sphinx

Tutorial: Build your first project

User Guides

Using Sphinx

Writing Sphinx Extensions

LaTeX customization

Sphinx Extensions API

Community

Get support

Contribute to Sphinx

Sphinx FAQ

Sphinx authors

Reference

Command-Line Tools

Configuration

Extensions

reStructuredText

Glossary

Changelog

Projects using Sphinx

Getting Started¶

Sphinx is a documentation generator or a tool that translates a set of plain

text source files into various output formats, automatically producing

cross-references, indices, etc. That is, if you have a directory containing a

bunch of reStructuredText or Markdown

documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),

man pages and much more.

Sphinx focuses on documentation, in particular handwritten documentation,

however, Sphinx can also be used to generate blogs, homepages and even books.

Much of Sphinx’s power comes from the richness of its default plain-text markup

format, reStructuredText, along with

its significant extensibility capabilities.

The goal of this document is to give you a quick taste of what Sphinx is and

how you might use it. When you’re done here, you can check out the

installation guide followed by the intro to the

default markup format used by Sphinx, reStructuredText.

For a great “introduction” to writing docs in general – the whys and hows, see

also Write the docs, written by Eric Holscher.

Setting up the documentation sources¶

The root directory of a Sphinx collection of plain-text document sources is

called the source directory. This directory also contains the Sphinx

configuration file conf.py, where you can configure all aspects of how

Sphinx reads your sources and builds your documentation. [1]

Sphinx comes with a script called sphinx-quickstart that sets up a

source directory and creates a default conf.py with the most useful

configuration values from a few questions it asks you. To use this, run:

$ sphinx-quickstart

Defining document structure¶

Let’s assume you’ve run sphinx-quickstart. It created a source

directory with conf.py and a root document, index.rst. The

main function of the root document is to serve as a welcome page, and

to contain the root of the “table of contents tree” (or toctree). This is one

of the main things that Sphinx adds to reStructuredText, a way to connect

multiple files to a single hierarchy of documents.

reStructuredText directives

toctree is a reStructuredText directive, a very versatile piece

of markup. Directives can have arguments, options and content.

Arguments are given directly after the double colon following the

directive’s name. Each directive decides whether it can have arguments, and

how many.

Options are given after the arguments, in form of a “field list”. The

maxdepth is such an option for the toctree directive.

Content follows the options or arguments after a blank line. Each

directive decides whether to allow content, and what to do with it.

A common gotcha with directives is that the first line of the content must

be indented to the same level as the options are.

The toctree directive initially is empty, and looks like so:

.. toctree::

:maxdepth: 2

You add documents listing them in the content of the directive:

.. toctree::

:maxdepth: 2

usage/installation

usage/quickstart

...

This is exactly how the toctree for this documentation looks. The

documents to include are given as document names, which in short

means that you leave off the file name extension and use forward slashes

(/) as directory separators.

Read more about the toctree directive.

You can now create the files you listed in the toctree and add content, and

their section titles will be inserted (up to the maxdepth level) at the

place where the toctree directive is placed. Also, Sphinx now knows about

the order and hierarchy of your documents. (They may contain toctree

directives themselves, which means you can create deeply nested hierarchies if

necessary.)

Adding content¶

In Sphinx source files, you can use most features of standard

reStructuredText. There are also several features added by Sphinx.

For example, you can add cross-file references in a portable way (which works

for all output types) using the ref role.

For an example, if you are viewing the HTML version, you can look at the source

for this document – use the “Show Source” link in the sidebar.

Todo

Update the below link when we add new guides on these.

See reStructuredText for a more in-depth

introduction to reStructuredText, including markup added by Sphinx.

Running the build¶

Now that you have added some files and content, let’s make a first build of the

docs. A build is started with the sphinx-build program:

$ sphinx-build -M html sourcedir outputdir

where sourcedir is the source directory, and outputdir is the

directory in which you want to place the built documentation.

The -M option selects a builder; in this example

Sphinx will build HTML files.

Refer to the sphinx-build man page for all

options that sphinx-build supports.

However, sphinx-quickstart script creates a Makefile and a

make.bat which make life even easier for you. These can be executed by

running make with the name of the builder. For example.

$ make html

This will build HTML docs in the build directory you chose. Execute

make without an argument to see which targets are available.

How do I generate PDF documents?

make latexpdf runs the LaTeX builder and readily invokes the pdfTeX

toolchain for you.

Todo

Move this whole section into a guide on rST or directives

Documenting objects¶

One of Sphinx’s main objectives is easy documentation of objects (in a

very general sense) in any domain. A domain is a collection of object

types that belong together, complete with markup to create and reference

descriptions of these objects.

The most prominent domain is the Python domain. For example, to document

Python’s built-in function enumerate(), you would add this to one of your

source files.

.. py:function:: enumerate(sequence[, start=0])

Return an iterator that yields tuples of an index and an item of the

*sequence*. (And so on.)

This is rendered like this:

enumerate(sequence[, start=0])¶

Return an iterator that yields tuples of an index and an item of the

sequence. (And so on.)

The argument of the directive is the signature of the object you

describe, the content is the documentation for it. Multiple signatures can be

given, each in its own line.

The Python domain also happens to be the default domain, so you don’t need to

prefix the markup with the domain name.

.. function:: enumerate(sequence[, start=0])

...

does the same job if you keep the default setting for the default domain.

There are several more directives for documenting other types of Python

objects, for example py:class or py:method. There is

also a cross-referencing role for each of these object types. This

markup will create a link to the documentation of enumerate().

The :py:func:`enumerate` function can be used for ...

And here is the proof: A link to enumerate().

Again, the py: can be left out if the Python domain is the default one. It

doesn’t matter which file contains the actual documentation for

enumerate(); Sphinx will find it and create a link to it.

Each domain will have special rules for how the signatures can look like, and

make the formatted output look pretty, or add specific features like links to

parameter types, e.g. in the C/C++ domains.

See Domains for all the available domains

and their directives/roles.

Basic configuration¶

Earlier we mentioned that the conf.py file controls how Sphinx

processes your documents. In that file, which is executed as a Python source

file, you assign configuration values. For advanced users: since it is

executed by Sphinx, you can do non-trivial tasks in it, like extending

sys.path or importing a module to find out the version you are

documenting.

The config values that you probably want to change are already put into the

conf.py by sphinx-quickstart and initially commented out

(with standard Python syntax: a # comments the rest of the line). To

change the default value, remove the hash sign and modify the value. To

customize a config value that is not automatically added by

sphinx-quickstart, just add an additional assignment.

Keep in mind that the file uses Python syntax for strings, numbers, lists and

so on. The file is saved in UTF-8 by default, as indicated by the encoding

declaration in the first line.

See Configuration for documentation of all available

config values.

Todo

Move this entire doc to a different section

Autodoc¶

When documenting Python code, it is common to put a lot of documentation in the

source files, in documentation strings. Sphinx supports the inclusion of

docstrings from your modules with an extension (an extension is a Python

module that provides additional features for Sphinx projects) called autodoc.

In order to use autodoc, you need to activate it in conf.py by

putting the string 'sphinx.ext.autodoc' into the list assigned to the

extensions config value:

extensions = ['sphinx.ext.autodoc']

Then, you have a few additional directives at your disposal. For example, to

document the function io.open(), reading its signature and

docstring from the source file, you’d write this:

.. autofunction:: io.open

You can also document whole classes or even modules automatically, using member

options for the auto directives, like

.. automodule:: io

:members:

autodoc needs to import your modules in order to extract the docstrings.

Therefore, you must add the appropriate path to sys.path in your

conf.py.

Warning

autodoc imports the modules to be documented. If any

modules have side effects on import, these will be executed by autodoc

when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their

main routine is protected by a if __name__ == '__main__' condition.

See sphinx.ext.autodoc for the complete description of the

features of autodoc.

Todo

Move this doc to another section

Intersphinx¶

Many Sphinx documents including the Python documentation are published on

the Internet. When you want to make links to such documents from your

documentation, you can do it with sphinx.ext.intersphinx.

In order to use intersphinx, you need to activate it in conf.py by

putting the string 'sphinx.ext.intersphinx' into the extensions

list and set up the intersphinx_mapping config value.

For example, to link to io.open() in the Python library manual, you need to

setup your intersphinx_mapping like:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

And now, you can write a cross-reference like :py:func:`io.open`. Any

cross-reference that has no matching target in the current documentation set,

will be looked up in the documentation sets configured in

intersphinx_mapping (this needs access to the URL in order to

download the list of valid targets). Intersphinx also works for some other

domain's roles including :ref:, however it doesn’t work for

:doc: as that is non-domain role.

See sphinx.ext.intersphinx for the complete description of the

features of intersphinx.

More topics to be covered¶

Other extensions:

Static files

Selecting a theme

Templating

Using extensions

Writing extensions

Footnotes

[1]

This is the usual layout. However, conf.py can also live in

another directory, the configuration directory. Refer to the

sphinx-build man page for more information.

© Copyright 2007-2024, the Sphinx developers.

Created using Sphinx 7.3.0.

GitHub - sphinx-doc/sphinx: The Sphinx documentation generator

GitHub - sphinx-doc/sphinx: The Sphinx documentation generator

Skip to content

Toggle navigation

Sign in

Product

Actions

Automate any workflow

Packages

Host and manage packages

Security

Find and fix vulnerabilities

Codespaces

Instant dev environments

Copilot

Write better code with AI

Code review

Manage code changes

Issues

Plan and track work

Discussions

Collaborate outside of code

Explore

All features

Documentation

GitHub Skills

Blog

Solutions

For

Enterprise

Teams

Startups

Education

By Solution

CI/CD & Automation

DevOps

DevSecOps

Resources

Learning Pathways

White papers, Ebooks, Webinars

Customer Stories

Partners

Open Source

GitHub Sponsors

Fund open source developers

The ReadME Project

GitHub community articles

Repositories

Topics

Trending

Collections

Pricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

You signed in with another tab or window. Reload to refresh your session.

You signed out in another tab or window. Reload to refresh your session.

You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

sphinx-doc

/

sphinx

Public

Notifications

Fork

2k

Star

6k

The Sphinx documentation generator

www.sphinx-doc.org/

License

View license

6k

stars

2k

forks

Branches

Tags

Activity

Star

Notifications

Code

Issues

1.1k

Pull requests

107

Discussions

Actions

Projects

0

Security

Insights

Additional navigation options

Code

Issues

Pull requests

Discussions

Actions

Projects

Security

Insights

sphinx-doc/sphinx

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

 masterBranchesTagsGo to fileCodeFolders and filesNameNameLast commit messageLast commit dateLatest commit History20,636 Commits.github.github  docdoc  sphinxsphinx  teststests  utilsutils  .codecov.yml.codecov.yml  .flake8.flake8  .git-blame-ignore-revs.git-blame-ignore-revs  .gitignore.gitignore  .mailmap.mailmap  .readthedocs.yml.readthedocs.yml  .ruff.toml.ruff.toml  AUTHORS.rstAUTHORS.rst  CHANGES.rstCHANGES.rst  CODE_OF_CONDUCT.rstCODE_OF_CONDUCT.rst  CONTRIBUTING.rstCONTRIBUTING.rst  EXAMPLES.rstEXAMPLES.rst  LICENSE.rstLICENSE.rst  MakefileMakefile  README.rstREADME.rst  bindep.txtbindep.txt  karma.conf.jskarma.conf.js  package-lock.jsonpackage-lock.json  package.jsonpackage.json  pyproject.tomlpyproject.toml  tox.initox.ini  View all filesRepository files navigationREADMELicenseSphinx

Sphinx makes it easy to create intelligent and beautiful documentation.

Sphinx uses reStructuredText as its markup language, and many of its strengths

come from the power and straightforwardness of reStructuredText and its parsing

and translating suite, the Docutils.

Features

Output formats: HTML, PDF, plain text, EPUB, TeX, manual pages, and more

Extensive cross-references: semantic markup and automatic links

for functions, classes, glossary terms and similar pieces of information

Hierarchical structure: easy definition of a document tree, with automatic

links to siblings, parents and children

Automatic indices: general index as well as a module index

Code highlighting: automatic highlighting using the Pygments highlighter

Templating: Flexible HTML output using the Jinja 2 templating engine

Extension ecosystem: Many extensions are available, for example for

automatic function documentation or working with Jupyter notebooks.

Language Support: Python, C, C++, JavaScript, mathematics, and many other

languages through extensions.

For more information, refer to the documentation.

Installation

The following command installs Sphinx from the Python Package Index. You will

need a working installation of Python and pip.

pip install -U sphinx

Contributing

We appreciate all contributions! Refer to the contributors guide for

information.

About

The Sphinx documentation generator

www.sphinx-doc.org/

Topics

python

markdown

documentation

docs

sphinx

documentation-tool

restructuredtext

Resources

Readme

License

View license

Activity

Custom properties

Stars

6k

stars

Watchers

149

watching

Forks

2k

forks

Report repository

Releases

37

Sphinx 7.2.6

Latest

Sep 13, 2023

+ 36 releases

Used by 347k

+ 347,006

Contributors

709

+ 695 contributors

Languages

Python

86.1%

TeX

6.5%

JavaScript

6.2%

HTML

0.8%

Common Lisp

0.3%

Makefile

0.1%

Footer

© 2024 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

概述 — Sphinx 1.8.5 文档

概述 — Sphinx 1.8.5 文档

主页

安装

文档

扩展/开发

导航

索引

模块 |

主页 |

文档 »

A

项目

Download

当前版本:

安装Sphinx:

pip install -U Sphinx

有问题吗？建议？

加入Google网上论坛的sphinx-users邮件列表:

或者来到FreeNode上的#sphinx-doc频道。

您还可以在跟踪器上打开问题

快速搜索

欢迎

用户说什么

“渴望一个伟大的工具，实际上让程序员想要编写文档！“

Sphinx是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档

它最初是为Python文档创建的，它具有出色的工具，可用于各种语言的软件项目文档。 当然，这个站点也是使用reStructuredText源创建的

输出格式: HTML（包括Windows HTML帮助），LaTeX（适用于可打印的PDF版本），ePub，Texinfo，手册页，纯文本

广泛的交叉引用: 语义标记和功能，类，引用，词汇表术语和类似信息的自动链接

分层结构: 轻松定义文档树，自动链接到平级，上级和下级

自动索引: 一般索引以及特定于语言的模块索引

代码处理: 使用Pygments荧光笔自动突出显示

扩展: 自动测试代码片段，包含Python模块（API文档）中的文档字符串等

贡献的扩展: 用户在第二个存储库中贡献了50多个扩展;其中大多数可以从PyPI安装

Sphinx使用reStructuredText作为其标记语言，其许多优点来自reStructuredText及其解析和翻译套件Docutils的强大功能和直接性。

文档

入门

基本任务概述

搜索页

搜索文档

目录

如需完整概述

总目录

所的函数，类，术语

变化

发布历史

您也可以从右下角的弹出菜单下载Sphinx文档的PDF/EPUB版本。

实际案例

可以在使用Sphinx的Projects页面上找到使用Sphinx生成的文档的链接。

有关Sphinx源文件外观的示例，请使用除此欢迎页面之外的文档所有页面上的“显示源”链接。

您可能还对如何使用matplotlib开发人员编写的Sphinx创建自定义文档的非常好的教程感兴趣

感谢日本Sphinx用户组，该文档有日文翻译。

O'Reilly出版了一本关于Sphinx的日语书:Sphinxをはじめよう/Learning Sphinx

主机

需要一个地方来托管你的Sphinx文档？ readthedocs.org已经托管了许多Sphinx文档，并且与项目的源代码控制很好地集成。 它还具有强大的内置搜索功能，超出了Sphinx基于JavaScript的离线搜索功能。

贡献者指南

如果您想为项目做出贡献，这部分文档适合您。

Sphinx开发人员指南

Sphinx 作者

导航

索引

模块 |

主页 |

文档 »

© 版权所有 2007-2019, Georg Brandl and the Sphinx team.

由 Sphinx 1.8.5 创建。