使用 Sphinx 的 ReadTheDocs 主题文件夹结构

【问题标题】：ReadTheDocs Theme folderstructure using Sphinx使用 Sphinx 的 ReadTheDocs 主题文件夹结构
【发布时间】：2018-06-18 23:59:33
【问题描述】：

我想创建我的讲义的数字版本。我安装了 sphinx 并更改了 config.py 文件，以便 ReadTheDocs 主题正常工作。

我希望有类似以下屏幕截图中的结构（来自Read the Docs Documentation）

我的 index.rst 看起来像

.. Lectures documentation master file, created by
   sphinx-quickstart on Tue Jan  9 20:20:10 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

iLectures
======================================

Hello!

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

   intro

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

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

如何更改 index.rst 以使其具有与屏幕截图中类似的结构？如果我可以在我的网站上有一个与导航相同的文件夹结构，那也很好吗？如何引用不在同一目录中的文件？我真的很感激任何帮助。尝试在 intro 之后缩进新内容，但它只会导致错误。

【问题讨论】：

标签： python-sphinx read-the-docs

【解决方案1】：

Read the Docs 的存储库有一个 docs 目录，该目录提供了一个示例，说明如何根据需要呈现导航。以下是对正在发生的事情的解释。

导航截图由yaml-config.rst和index.rst这两个文件生成。在后者中，您会看到它在 toctree directive 下方引用了 yaml-config.rst。

.. toctree::
   :maxdepth: 2
   :caption: User Documentation

   getting_started
   versions
   builds
   features
   support
   faq
   yaml-config
   guides/index
   api
   embed

index.rst 文件描述了整个文档集的文件结构，并在导航中表示为 maxdepth 的 2。 yaml-config.rst 文件被 Sphinx 解析并在“Read the Docs YAML Config”下呈现导航节点。

【讨论】：

感谢您的回答。只要我有时间尝试这个解决方案，我就会接受答案。