文档生成工具

Sphinx

Sphinx最初用于生成Python代码文档，支持多种语言软件项目的文档生成。支持：输出HTML、LaTeX、ePub、manual页面等、自动交叉引用以及代码高亮等。Sphinx使用reStructuredText作为标记语言（类似于Markdown，标记语法更多）¹。

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².

安装

独立安装

apt install python3-sphinx  # yum install python-sphinx, choco install sphinx

如果系统不存在Python环境，将自动安装Python环境；

虚拟环境安装

使用virtualenv或conda虚拟环境。如果用于生成代码文档，应该安装在代码开发所在虚拟环境中，因为在导入代码模块时会导入其中的依赖项。因此，独立的虚拟环境无法满足依赖。

conda activate env_dev && conda install sphinx -c conda-forge

Getting Started with Sphinx — Read the Docs 5.21.0 documentation

Sphinx tutorial — Sphinx documentation (sphinx-doc.org)

配置和编译

sphinx-quickstart  # 自动生成配置文件和编译脚本(make.bat)
sphinx-build -b html sourcedir builddir # => make html

sourcedir：Sphinx项目使用的所有源文件所在目录（子目录）

语言：默认为英语en，可选择设置中文zh_CN。

Configuration — Sphinx documentation (sphinx-doc.org)

首页配置文件

定制文档首页以及目录。

.. toctree::
   :maxdepth: 2

   usage/installation   添加要转换的文件：省略扩展名，使用`/`作为路径分隔符
   usage/quickstart
   ...

被添加文件所引用的文件也会被解析。

文件路径

编译配置文件

主题：

conda install -c conda-forge sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'   # in conf.py
extensions = [ 'sphinx_rtd_theme' ]

Sphinx Themes Gallery (sphinx-themes.org)

解析和转换Python代码

extensions = [
  'sphinx.ext.autodoc',
  'sphinx.ext.napoleon'  # 使用Numpy/Google风格代码注释
]

NumPy风格代码注释：可在VS Code中使用autoDocstring自动生成模板并修改内容。

sphinx.ext.napoleon – Support for NumPy and Google style docstrings — Sphinx documentation (sphinx-doc.org)

注释章节标题：

Parameters|Arguments|Args/Keyword Args|Keyword Arguments：参数说明；

Return|Returns：返回值说明；

Raise|Raises：抛出异常说明；

Example|Examples：示例；

References/See Also：参考文献或跳转链接；

Tip/Note/Warns|Warn/Todo：额外的提示信息。

自动导入模块内容：

.. automodule:: my.module
   :members:                    自动导入所有内容并生成文档
.. autoclass:: my.module.class
   :members: open, close        导入指定内容并生成文档

sphinx.ext.autodoc – Include documentation from docstrings — Sphinx documentation (sphinx-doc.org)

使用sphinx-apidoc可自动扫描指定模块中的内容，并生成对应的.rst文件。

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]
#-f,--force
#-e, --separate        put documentation for each module on its own page
#-M, --module-first    put module documentation before submodule documentation

包含__init__.py的目录才会被识别为子模块。

解析和转换Markdown文件 3

安装插件：

conda install myst-parser -c conda-forge

更新Sphinx配置文件：配置处理的文件格式扩展名，以及支持的Markdown扩展。

extensions = ['myst_parser']
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}
myst_enable_extensions = [...]  # optional depends: linkify-it-py

myst-parser不能转换代码中Markdown格式的注释文档。

d2lbook

安装

conda create -n d2lbook -c conda-forge python=3.8 sphinx pandoc librsvg
conda activate d2lbook
git clone https://github.com/d2l-ai/d2l-book.git
pip install ./d2l-book

如果需要编译为PDF需要安装一个LaTeX发行版（如TexLive或MikTeX），librsvg用于将SVG转换为PDF文件。

编写编译配置文件

[build]
index = index                        # 默认首页index.md
notebooks = *.md source/*.md         # 需要将markdown文件放在notebooks类别才会输出内容
exclusions = source/get_started.md   # 排除文件
non-notebooks = 
eval_notebook = False                # 是否执行代码块中的代码
tabs = mxnet, pytorch, tensorflow    # 多标签内容

编写文档

和Sphinx的首页文件类似，在首页文件（index.md）中添加目录：

````toc
source/get_started
source/reference
````

编写正文：

使用:begin_tab:和:end_tab:来标记标签页，以生成多标签页面。

:begin_tab:`mxnet`
接下来，我们实例化`mxnet`类并访问其模型参数。
:end_tab:

在代码块中，使用#@tab tabname来标记相应标签（默认为配置文件中声明的第一个标签）。

```python
#@tab pytorch
import torch
from torch import nn
import torch.nn.functional as F
```

编译

生成HTML文件：

d2lbook build --tab all html  # 需要执行两次，否则可能出现错误（找不到index.rst）

编译前可能需要执行d2lbook clear（rm -rf _build），否则更改内容可能不会被重新编译。

修改主题资源

在线资源处理：主题中的部分字体图片资源需要在线下载，如果网络不佳或离线使用会使页面等待加载。因此，可以将这些资源预先下载到本地，并修改资源文件使用本地资源路径（文件或本地http URL）替换相应资源URL。

字体：将_build/html/_static/font.css（来自安装的mxtheme主题）中以//fonts.gstatic.com开头的字体URL添加协议https:，使之能被正常访问；其次，将其中的字体URL提取出来并批量下载到本地，然后将font.css中的URL替换为本地路径。

图片：修改d2l-book的sphinx_template模块引用的在线资源文件为本地文件加快访问速度。

https://raw.githubusercontent.com/choldgraf/sphinx-copybutton/master/sphinx_copybutton/_static/copy-button.svg -> PREFIX/_static/copy-button.svg

服务：注释d2l-book.sphinx中生成的访问google-analytics的JavaScript代码；

2. User Guide — D2L-Book: A Toolkit for Hands-on Books 0.1.17 documentation

doxygen

Doxyfile

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "Triangle Library"
PROJECT_NUMBER         = 1.1
PROJECT_BRIEF          = "Triangle Library for C++ Documentation Tutorial"
OUTPUT_DIRECTORY       = "build" 
FULL_PATH_NAMES        = NO
INPUT                  = "source/path"
RECURSIVE              = YES
GENERATE_XML           = NO
GENERATE_LATEX         = NO
GENERATE_RTF           = NO 
GENERATE_MAN           = NO

mdBook

安装

下载mdbook。

创建工作目录并初始化项目（作者、项目标题，信息位于工作目录下的book.toml文件中）。

mdbook init book_path
       --theme       # 将主题文件复制到工作目录下以便修改默认配置(./theme/)
       --title TITLE # 未指定改选项则提示用户输入标题
       --ignore      # 生成默认的.gitignore文件(其中包含book目录)

项目的Markdown文档内容位于src/目录下（Markdown文件内不能超链接该目录外的文件，可通过符号链接将外部文档置于src/下），src/SUMMARY.md是所有文档的入口。

修改./theme/css/general.css以自定以标题和正文以及代码块的字体字号。

安装插件

从插件仓库下载发行版本，并释放到mdbook同一目录下（将该目录加入路径变量）。

✨mdbook-theme: A preprocessor and a backend to config themes for mdbook, especially creating a pagetoc on the right and setting full color themes from the offical ace editor. (github.com)

slowsage/mdbook-pagetoc: Adds sidebar table of contents. (github.com)

下载安装侧边栏目录插件：

[preprocessor.pagetoc]
[output.html]
additional-css = ["theme/pagetoc.css"]
additional-js  = ["theme/pagetoc.js", "theme/MathJax.js"]
no-section-label = true

lzanini/mdbook-katex: A preprocessor for mdBook, rendering LaTeX equations to HTML at build time. (github.com)

[output.html]
theme = "mytheme"
mathjax-support = true  # 暂不支持$$标记的数学公式
# [output.pdf]
# mdbook-pdf 利用chrome提供的PDF生成功能生成PDF文件，无法控制文档格式。

文档结构

# Summary
[prefix_chapter](./prefix.md)
# Part Title
- [chapter name](./chapter_name.md)
  - [sub_chapter_name](./some_path/sub_chapter_name.md)
--- <!-- separater line -->
[suffix_chapter](./suffix.md)

以-开头的声明为编号章节，通过缩进区分大纲级别，可在编号章节前后添加无编号的序言/附录等内容（不可出现在编号章节之间，不可缩进嵌套）。

如果章节声明的超链接为空，则在目录中该章节无法点击。

使用---以在目录中添加分割线。

渲染文档

使用mdBook内置服务

mdbook serve --open   # 在工作目录下执行

项目目录下的源文件修改后，mdBook将会重新编译内容并刷新浏览页面。

编译发布

mdbook build 
       --dest-dir [book_path] # 生成HTML文件，输出到指定目录(默认为./book/)
       --open                 # 打开编译结果

编译过程会将源文件目录下的除.md外的所有文件复制到输出目录下。

编译输出内容可通过HTTP服务进行发布。

MkDocs

安装MkDocs

conda create -n mkdocs mkdocs

安装插件

pip install mkdocs-section-index mkdocs-exclud

创建项目

mkdocs new [dir-name] # Create a new project.

编译配置

theme:
  docs_dir: docs
  site_dir: site
  include_sidebar: true
  use_directory_urls: false  #*

*：问题：附件相对路径多了一层当前文档名，如./docs/docs.assets/xyz.png，正确形式应该为./docs.assets/xyz.png。

构建项目

mkdocs serve          # Start the live-reloading docs server.
mkdocs build          # Build the documentation site.

Learning Programming Book

文档生成工具

Sphinx

安装

独立安装

虚拟环境安装

配置和编译

首页配置文件

编译配置文件

解析和转换Python代码

解析和转换Markdown文件 3

d2lbook

安装

编写编译配置文件

编写文档

编译

修改主题资源

doxygen

Doxyfile

mdBook

安装

安装插件

项目配置

预处理器

渲染器

文档结构

渲染文档

使用mdBook内置服务

编译发布

MkDocs

安装MkDocs

安装插件

创建项目

编译配置

构建项目

gitbook

插入文档作为子页面

与git仓库(GitHub或GitLab)同步

参考资料