sphinx写文档的简单尝试--index.rst的内容分析

先说简单的结论，

rst上手难度远高于markdown, 功能扩展完爆markdown

在安装sphinx后，开始编写shpinx的第一步，就是使用sphinx-quickstart来生成配置文件

我的目录结构大概是

xxx/
    abc/
        .....
    docs/
        conf.py
        index.rst
        ....

conf.py就是相关的配置（包含主题，插件等的设置），index.rst是默认生成的主文档

Contents:

.. toctree::
   :maxdepth: 2


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

这篇文章主要讲解默认的index.rst中的相关配置，而不再单独的闲扯诸如字体样式那些东西（那些也相对容易）

restructure有两种命令，一种是..打头的，另一种是:xxx:这样的．

.. toctree::声明了一个树状结构，　:maxdepth: 2指定了在这个页面最多展示两级

目录与索引

下面假设我在docs目录下新建了两个文件test.rst, test2.rst，　并将index.rst修改为

.. toctree::
   :maxdepth: 1

   test
   test2

而test.rst中的内容为

test
=====

.. toctree::
   :maxdepth: 2

   test2

haha

.. index:: test

test2.rst中内容为

test2
========

此时index.rst中的doctree引入了test, test2两个页面的链接 而其中的maxdepth指定，决定了在index页面树状结构显示的层级． 而test.rst中的.. index:: test生成了一个索引, 其会被添加在index界面中* :ref:genindex指向的索引页面中

文档自动生成

在conf.py中需要开启autodoc插件

extensions = ['sphinx.ext.autodoc']

然后在需要的页面中添加

.. automodule:: my_package
   :members:

my_package为代码的报名，有了这样的配置在生成文档时会向* :ref:modindex指向的包索引页面中添加相应的索引，automodule还有很多功能，具体这里不再详述．

注：autodoc是自动生成的，如果需要手动生成，可以使用sphinx-apidoc这个命令来完成

转载于:https://my.oschina.net/pingf/blog/751599