sphinx python

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

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

sphinx语法文档规范： 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 之间需要空一格，才能生效