Read the Docs index.rst目录

Getting Started

Getting Started

[译]Read the Docs 入门

index.rst

运行

sphinx-quickstart

以后，你将会得到一个

index.rst

，这相当于整个文档的目录。

现在，它因该是这样的：

.. Project documentation master file, created by
   sphinx-quickstart on Sat May  5 18:00:00 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Project's documentation!
===================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


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

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

1. 新建

   .rst

   文件（如果你安装了

   recommonmark

   并且在

   conf.py

   中配置了Markdown，也可以是

   .md

   文件）用于放置源。在第一行写入标题，第二行多个

   =

   。
2. 在

   index.rst

   中

   :caption: Contents:

   后面几行加入其相对路径（注意缩进，原文件是三个空格）。

   比如：（

   source.rst

   对应

   docs/source.rst

   ，

   source/markdown.md

   对应

   docs/source/markdown.md

   ）

.. toctree::
   :maxdepth: 
   :caption: Contents:

   source.rst
   source/markdown.md
           

然后

make html

，可以看见目录中多出来了两篇文档。分别对应源文件第一行的标题。

接着，还可以增加并修改Part的名称：

.. toctree::
   :maxdepth: 
   :caption: Part :
   .rst

.. toctree::
   :maxdepth: 
   :caption: Part :
   .rst
           

make html

以后，可以看见目录文章标题前多出了

Part 1

、

Part 2

的标记。