Read the Docs index.rst目录

最新推荐文章于 2025-06-05 09:07:30 发布

原创最新推荐文章于 2025-06-05 09:07:30 发布 · 2.2k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#Read the Docs #index.rst

Python 专栏收录该内容

4 篇文章

订阅专栏

本文档介绍了如何使用ReadtheDocs创建项目的文档。通过运行sphinx-quickstart命令生成index.rst文件作为文档的基础结构，并展示了如何添加新的.rst或.md文件来丰富文档内容。此外，还介绍了如何组织文档结构及如何通过make html命令生成HTML文档。

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`

新建.rst文件（如果你安装了recommonmark并且在conf.py中配置了Markdown，也可以是.md文件）用于放置源。在第一行写入标题，第二行多个=。
在index.rst中:caption: Contents:后面几行加入其相对路径（注意缩进，原文件是三个空格）。
比如：（source.rst对应docs/source.rst，source/markdown.md对应docs/source/markdown.md）

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

   source.rst
   source/markdown.md

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

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

.. toctree::
   :maxdepth: 2
   :caption: Part 1:
   1.rst

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

make html以后，可以看见目录文章标题前多出了Part 1、Part 2的标记。