# SphinxAuto

**Repository Path**: zypdominate/sphinx-auto

## Basic Information

- **Project Name**: SphinxAuto
- **Description**: 一键实现 sphinx 文档的生成、更新和部署。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-02
- **Last Updated**: 2025-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Usage of Sphinx

在线展示我的Demo: [Content — Sphinx-Auto 2.0 documentation](https://sphinx-auto.readthedocs.io/en/latest/index.html)

## 关于

现在自动化框架暂无清晰的API文档，给今后的代码编写、查阅及维护造成一定的困扰，为了实现将所有测试用例脚本中的注释导出、查阅，查阅网上多数人使用的工具，决定采用sphinx实现自动产生参考文档、索引等。

sphinx的优点：

- 支持多种输出格式：html、Latex、ePub等；
- 丰富的扩展
- 结构化文档
- 自动索引
- 支持语法高亮

环境配置

- 安装 Python3
- sphinx：`pip install sphinx`



## 常规操作

1. 进入 doc 目录下，输入 `sphinx-quickstart`，会出现一些选项，根据需要填写即可

   ```bash
   PS D:\Developer\SphinxAuto\doc> sphinx-apidoc -o ./source ../src/
   PS D:\Developer\SphinxAuto\doc> sphinx-quickstart
   Welcome to the Sphinx 8.1.3 quickstart utility.
   Please enter values for the following settings (just press Enter to
   accept a default value, if one is given in brackets).
   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]: y
   
   The project name will occur in several places in the built documentation.
   > Project name: Sphinx-Auto
   > Project release []: 2.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.
   > Project language [en]: zh_CN
   
   Creating file D:\Developer\SphinxAuto\doc\source\conf.py.
   Creating file D:\Developer\SphinxAuto\doc\source\index.rst.
   Creating file D:\Developer\SphinxAuto\doc\Makefile.
   Creating file D:\Developer\SphinxAuto\doc\make.bat.
   
   Finished: An initial directory structure has been created.
   
   You should now populate your master file D:\Developer\SphinxAuto\doc\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.
   ```

2. 然后出现以下目录结构：

   ```
   doc
   ├── build
   ├── source
   │   ├── conf.py
   │   ├── index.rst
   │   ├─_static
   │   └─_templates
   ├── make.bat
   └── Makefile
   ```

3. 部分分解说明

   - **Makefile**：可以将它看作是一个包含指令的文件，在使用 `make` 命令时，使用这些指令来构建文档输出。
   - **build**：这是触发特定输出后用来存放所生成的文件的目录。
   - **conf.py**：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 `sphinx-quickstart` 时选中的那些值。
   - **index.rst**：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

4. conf.py文件中可以修改配置：

   配置confi.py：

   ```python
   import os
   import sys
   sys.path.insert(0, os.path.abspath('../../src'))  # 指向src(需要导出用例的目录)
   ```

   为sphinx添加扩展：

   ```python
   extensions = ['sphinx.ext.autodoc',
       'sphinx.ext.doctest',
       'sphinx.ext.intersphinx',
       'sphinx.ext.todo',
       'sphinx.ext.coverage',
       'sphinx.ext.mathjax',
       'sphinx.ext.napoleon'
   ]
   ```

   更换sphinx的主题：

   ```python
   # html_theme = 'alabaster' 默认主题
   import sphinx_rtd_theme    # 需要先pip install sphinx_rtd_theme
   html_theme = 'sphinx_rtd_theme'
   html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
   ```

   大部分主题 [Sphinx Themes Gallery (sphinx-themes.readthedocs.io)](https://sphinx-themes.readthedocs.io/en/latest/#themes)，特别是对于命名+入参很长的函数,显示效果都不如 furo 和 sphinx_book_theme 。

   使用发现这两个主题有一些差异：

   - furo
     - 在渲染 markdown 文件时，会将所有一级标题（`#` 标题）都显示在侧边栏中，因此会展示 README.md 文件中的所有一级标题（如 Usage、接口文档、其他注意事项 等）
     - 展示 python 模块时，右侧边栏会列出所有的函数，包括类的方法
   - sphinx_book_theme
     -  在渲染 markdown 文件时，默认只显示第一个一级标题，不展开后续的一级标题内容，简化左侧边栏，不支持定制
     -  展示 python 模块时，右侧边栏只会列出类名、函数，不包括类的方法

5. 生成html文件

   进入 doc 目录，如下操作，会把src所有文件一次性生成，可能会产生重复内容：

   ```shell
   sphinx-apidoc -o ./source ../src/ # 这是将src目录下的所有py脚本注释导出，包括src中所有子目录中的脚本
   ```

   需要导出哪个目录的脚本注释，就单独导出。

   正确操作：命令行切换到doc目录下，依次执行：

   ```
   sphinx-apidoc -o [生成rst的位置] [项目代码的位置] -f(强制重新覆盖写，否则会检测，如果有同名文件存在，会跳过不更新)
   ```

   ```shell
   sphinx-apidoc -o ./source ../src/scripts1/  # 这是将src/scriptes1/目录下的所有py脚本注释导出，包含子目录中的py脚本
   sphinx-apidoc -o ./source ../src/scripts2/
   ```

   再执行：

   ```shell
   make clean  # 删除build目录下的文件（第一次build为空文件夹）
   make html	# 在build目录下生成 doctrees、html 目录
   ```

   确认最后输出中含有 `build succeesed`，再去build/html目录中检查是否生成了对应的html等其他文件。

6. 谷歌浏览器打开build/html/index.html，查看API文档

有个问题，`sphinx-apidoc -o ./source ../src/` 方式生成的 .rst 文件后，打开 html，没有展示出各个模块，需要手动去修改 index.rst 文件，很复杂。所以不采用这种命令生成方式。而是手动配置 .rst 文件， 不断调试，让页面展示成我想要的样子，接着用 python 脚本处理，自动化构造 .rst 文件。

---

## 一键生成文档

为了省事，编写  [auto_generate.py](auto_generate.py) ，完成文档的编译和更新，并在浏览器中打开。

脚本已经很好地实现了自动化生成 Sphinx 文档的功能，包括创建 `.rst` 文件、构建 `index.rst` 索引、拷贝 README 文件，并调用 `sphinx-autobuild` ，在生成 .rst 文件后进行编译，生成实时 HTML 文档。不用再手动执行  `make clean`，`make html` 手动编译。

自动化脚本没有使用 `sphinx-apidoc` 来生成 .rst 文件，而是构造色生成 .rst 文件，通过排版布局，来显示文档。

`index.rst` 文件

```rst
Content
==================
.. toctree::
   :maxdepth: 2

   README
   module1/script_a.rst
   module1/submodule1/script1.rst
   module1/submodule2/script2.rst
   module2/script_b.rst
   module2/submoduleA/sub_script_a.rst
   module2/submoduleB/sub_script_b.rst

Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
```

<img src="./images/sphinx1.png"/>

<img src="./images/sphinx2.png"/>

---

## 启动服务查看

- 本地直接打开 html 文件， [Content — Sphinx Demo 2.0 文档](file:///D:/Developer/SphinxAuto/doc/build/index.html)

- 使用 python3 自带的 `http.server` 模块快速启动一个静态文件服务器

  `python -m http.server 8001`

  ```bash
  PS D:\Developer\SphinxAuto\doc\build> python -m http.server 8001 
  Serving HTTP on :: port 8001 (http://[::]:8001/) ...
  ::ffff:127.0.0.1 - - [02/Nov/2024 01:01:20] "GET / HTTP/1.1" 200 -
  ::ffff:127.0.0.1 - - [02/Nov/2024 01:01:20] "GET /_static/pygments.css?v=a746c00c HTTP/1.1" 200 -
  ```

  执行命令，在 `doc/build` 启动一个 HTTP 服务器，访问：[Content — Sphinx Demo 2.0 文档](http://127.0.0.1:8001/)

- Sphinx 内置服务器

  ```bash
  pip install sphinx-autobuild
  ```

  ```bash
  sphinx-autobuild <source_dir> <build_dir> --host 0.0.0.0 --port 8001
  sphinx-autobuild .\source\  .\build\  --host 0.0.0.0 --port 8001
  ```

  ```bash
  PS D:\Developer\SphinxAuto\doc> sphinx-autobuild .\source\  .\build\  --host 0.0.0.0 --port 8001
  [sphinx-autobuild] Starting initial build
  [sphinx-autobuild] > python -m sphinx build '.\source\' '.\build\'
  Running Sphinx v8.1.3
  loading translations [zh_CN]... done
  WARNING: html_static_path entry '_static' does not exist
  loading pickled environment... The configuration has changed (4 options: 'html_permalinks_icon', 'html_sourcelink_suffix', 'html_theme_options', 'templates_path')
  done
  myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=
  ('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta=
  {}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_di
  gits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
  building [mo]: targets for 0 po files that are out of date
  writing output... 
  building [html]: targets for 0 source files that are out of date
  updating environment: 0 added, 0 changed, 0 removed
  reading sources... 
  looking for now-outdated files... none found
  no targets are out of date.
  build succeeded, 1 warning.
  
  The HTML pages are in build.
  [sphinx-autobuild] Serving on http://0.0.0.0:8001
  [sphinx-autobuild] Waiting to detect changes...
  ```

  访问：[Content — Sphinx Demo 2.0 文档](http://127.0.0.1:8001/)

  好处：监测 doc 目录中的文件是否变化，在第一次编译成功后，只要改动了文件内容、文件位置变化等，它会自动重新编译。当然，如果是 src 工程代码变化，不会被自动检测到，需要手动更新 rst 文件。

---

## sphinx 语法

sphinx采用 reStructuredText (reST) 的概念和语法 。

1. 章节标题： 在双上划线符号之间（或为下划线）, 并且符号的长度不能小于文本的长度: 

   ```
   Welcome to UTest API documentation!
   =======================================
   
   ```

   通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:

   - `#` 及上划线表示部分
   - `*` 及上划线表示章节
   - `=`, 小章节
   - `-`, 子章节
   - `^`, 子章节的子章节
   - `"`, 段落

2. 内联标记 (与markdown语法一致)

   - 星号: `*text*`   斜体： *example演示*
   - 双星号: `**text**`  加粗 ：**example演示**
   - 反引号: \`\`\`code\`\`\`   代码样式： ```example演示```

    **注**：星号及反引号在文本中容易与内联标记符号混淆，可使用反斜杠符号转义. 

   标记的一些限制：

   - 不能相互嵌套
   - 内容前后不能由空白: 这样写``* text*`` 是错误的
   - 如果内容需要特殊字符分隔. 使用反斜杠转义，如: `thisis\ *one*\ word`

3. 列表

    列表标记仅在段落的开头，列表可以嵌套，但是需跟父列表使用**空行分隔** 

   ```
        * Item Foo
   
           * childitem foo1
           * childitem foo2
   
        * Item Bar
   
           1. childitem bar1
           2. childitem bar2
           
            #. Item 1
        #. Item2
        
           * childitem foo1
           * childitem foo2
   
        1. item3
        2. item4
   
           1. childitem1
           2. chidlitem2
   
   ```

4. 跳转到某一标签

   方式一：

    标签直接放在章节标题前面

   在 demo1.rst 中设置标签：

   ```
   .. _demo1.py-label:
   
   demo1 module
   ============
   
   ```

    在其他文件中可以通过 :ref:\`demo1.py-label\` 来跳转

   ```
   :ref:`demo1.py-label`.
   
   ```


   方式二：

    标签不放在章节开头，但是需要给出明确的链接

   在demo3.rst中设置标签，此时标签可以不放在章节开头：

   ```
   demo3 module
   ============
   .. _demo3.py-label:
   
   ```

    在其他文件中可以通过 :ref:\`name <demo3.py-label>\`. 来跳转，这里name可以任意命名

   ```
   :ref:`name <demo3.py-label>`.
   
   ```

5. 显性标记

   显性标记不展示在html中，有点像注释的感觉。主要是用在那些需做特殊处理的reST结构中，如尾注，突出段落，评论，通用指令。显式标记以 `..` 开始，后跟空白符，段落的缩进一样。（在显示标记与正常的段落间需有空行）

   ```
   .. sphinx_demo documentation master file, created by
      sphinx-quickstart on Fri Nov  1 11:10:41 2019.
   
   .. toctree::
      :maxdepth: 4
      :caption: Contents:
   
   ```

6. 某个测试框架使用模板：

   ```python
   def test_123():
       """
       [用例描述]：
           版本测试用例简述（通俗易懂）
       [测试策略]：
           * 跳过条件；
           * 设备间策略差异等.
       [测试数据]：
           1. 示例1:遍历测试所有支持的编码格式
           2. 示例2:不同采集制式下，遍历不同ucode模式
       [前置条件]：
           1. module-setup_module:
           2. class-setup_class:
           3. function-setup_function:
       [测试步骤]：
           1. 示例1：
               1. 设置（修改）。。。。，检查。。。；
               2. 设置。。。。，检查。。。；
               3. 设置。。。。，检查。。。；
           2. 示例2：
               1. 设置。。。。；
               2. 设置。。。。；
               3. 检查的违章包括：
                   * 压线、 11
                   * 压双黄线、 9
                   * 压单黄线、10
                   * 逆行、2
       [后置条件]：
           1. function-setup_function:
           2. class-setup_class:
           3. module-setup_module:
       """
       pass
   
   ```

   注意点：

   1. 注释中的换行一律使用Enter，然后使用Tab缩进；
   2. 在[用例描述]：[测试策略]：这样的标题后面不要写文字，Enter换行后写； 如果没有需要添加的内容，换行后写“无”字；
   3. 对于选择用序号1.2.3还是* ， 如果有明确的先后步骤请使用1.2.3. ， 没有先后顺序或步骤根据自己审美选择用1.2.3或* ；
   4. 使用1.2.3.时需要英文输入法, 同时注意标记符号与 内容之间需要有空格；

---

## Reference

1. 代码风格：

   - [styleguide | Style guides for Google-originated open-source projects](https://google.github.io/styleguide/pyguide.html#doc-function-args)

   - [Example — numpydoc v1.9.0rc0.dev0 Manual](https://numpydoc.readthedocs.io/en/latest/example.html#example)

2. markdown 纯文档 sphinx demo

   [source/Cpp/01设计模式/index.rst · xxpcb/SphinxDemo - 码云 - 开源中国 (gitee.com)](https://gitee.com/xxpcb/sphinx-demo/blob/master/source/Cpp/01设计模式/index.rst)

   小记：他这边用了多个 index.rst，配合多级目录，嵌套使用，侧边栏可以点击展开。