sphinx python

今天药忘吃喽~ 2022-02-18 15:25 215阅读 0赞

由于python命令大小写敏感, 查看版本号必须用大写的-V命令

step 1: window环境下用spinx生成html文档

sphinx语法文档规范： [https://pythonhosted.org/an\_example\_pypi\_project/sphinx.html][https_pythonhosted.org_an_example_pypi_project_sphinx.html]

运行：在根目录下$ make html，就可以在build 路径下产生html 文件

**新生成html文件**：在根目录下创建`example.rst，`还需要将它列在 `toctree` 中，但要谨慎操作。文件名后面需要有一个间隔，这样文件名清单才会有效，该文件不需要文件扩展名（在本例中为 `.rst`）

index.rst 中的 toctree 示例：

> Contents:
> 
> .. toctree::
> 
>    :maxdepth: 2
> 
>    example

在根目录下$ make html，就可以在build 路径下产生example.html 文件。

**index.rsf文件详解：**

其中，**toctree**（table of contents） 代表文档的目录页，*toctree *是sphinx 指令，主要功能是将多个文件链接到一个单一页面中组成层级结构。（说人话：生成文档目录）。maxdepth 代表目录显示的最大层级。

*toctree* 命令初始化是空的，像下面这样：

.. toctree::
        :maxdepth: 2

在 *source *文件夹中，新建一个叫做 ***usage*** 的文件夹，再在 *usage* 文件夹中新建两个文件，分别命名为 installation.rst、quickstart.rst。

上面的 toctree 指令内容改成如下这样。

.. toctree::
        :maxdepth: 2
    
        usage/installation
        usage/quickstart

如此，toctree 指令使用 文档名称（省略后缀名）作为目录的中的链接地址。使用 **/（正斜杠）**作为路径分隔符。总之，目录的结构就是按照文件夹中文件的编排来进行布置。需要在目录中链接什么文件，就将该文件之于source路径的**相对路径**填写在toctree之后就可以。而maxdepth是代表目录中链接的文件的文章层级，比如上述代码中，链接installation.rst文件中的一级标题和二级标题的内容，在目录页面，也就是当前的index.rst页面中显示。

需要注意的是：

*  形如 usage/installation 作为 toctree指令的 内容（content）需要跟在可选项（options）的后面，**空一行**，才能发挥作用
 *  maxdepth 作为 toctree指令的 可选项（options），**:maxdepth:** 和 **2** 之间需要空一格，才能生效

[https_pythonhosted.org_an_example_pypi_project_sphinx.html]: https://pythonhosted.org/an_example_pypi_project/sphinx.html