为 sphinx 组织 .rst 文件？答案

【问题标题】：Organise .rst files for sphinx?为 sphinx 组织 .rst 文件？
【发布时间】：2017-03-31 17:39:20
【问题描述】：

我正在整理一些使用 Sphinx 的用户指南。但是，有许多 .rst 文件，当它们与 index.rst 一起位于主文件夹中时，要跟踪它们变得相当困难。

我想像这样将它们组织到文件夹中。但是随后，make html 命令导致警告说它无法找到隐藏在文件夹中的所有 .rst 文件。

如何组织我的.rst 文件？

index.rst
  Docs
     new_starter.rst
     subject_guides.rst
  New starter
     first_week.rst
     second_week.rst
  Subject guides
     stress.rst
     aerodynamics.rst
     data_science.rst

【问题讨论】：

相关：stackoverflow.com/questions/10199233/…

标签： python python-sphinx

【解决方案1】：

这在 Sphinx 文档部分 TOC Tree 中有所提及。

在您的index.rst 中，使用toctree 指令：

Project Awesome
===============

Welcome to the Project Awesome docs.

.. toctree::
   :glob:
   :maxdepth: 2

   docs/*
   new_starter/*
   subject_guides/*

上面使用“globbing”，但您可以使用文件名而不是 globbing 显式排序文件。

【讨论】：

我试过了。顺便说一下，它需要:glob: 。我仍然有侧栏无法正常加载的问题。
您期望和观察到什么？什么是“适当”？这可能是一个主题问题。
我正在使用readthedocs 主题。当我浏览文档时，侧栏没有更新自身并显示较低的级别。但是，我确实找到了解决方法：我删除了构建文件并再次运行 make html。它现在正在工作:)
啊，是的。 Sphinx 使用缓存并仅重建更改的文件。 make clean html 而不是 make html 也应该“清理”缓存。