如何用 Sphinx 注释掉一个目录树条目？答案

【问题标题】：How to comment out a toctree entry with Sphinx?如何用 Sphinx 注释掉一个目录树条目？
【发布时间】：2021-04-02 09:43:09
【问题描述】：

我是 Sphinx 的新手，我似乎没有找到实现这一目标的方法。我希望能够随着我的进步快速评论/取消评论单个目录树条目，而不必删除该行。我曾经在 Latex 中执行此操作，以减少我的项目仍在进行中的编译时间。

例如，我想实现这样的目标：

.. toctree::
   
   file1
   file2
   .. file3   (I want to comment/uncomment this, easily)
   file4
   ..  file5  (this also fails)
   ..
       file6  (this also fails)

正确的做法是什么？

【问题讨论】：

这对我有用。我只是收到一个警告：WARNING: toctree contains reference to nonexisting document '.. file3'，并且文档构建。如果你仍然看到一个构建的页面，那么你首先需要make clean删除最初构建的文件。
是的，我已经注意到了，但一方面我认为这不是真正的解决方案（因为我会收到很多警告，使我的编译输出不整洁），但更重要的是，当使用自定义标题（例如Title 3 <file3>）那么它根本不起作用。它将编译文档 file3（这是我想要避免的），并将在生成的 html 上将链接显示为“.. Title 3”。

标签： python-sphinx toctree

【解决方案1】：

您是否尝试过在 toctree 指令下使用 :hidden: 选项？我想你需要有两个单独的 toctree 指令来实现这一点：

.. toctree::

    visiblefile1
    visiblefile2

.. toctree::
    :hidden:

    hiddenfile1
    hiddenfile2

另见sphinx-doc.org。

也许这会达到可接受的结果。它不完全是评论/取消评论，但它达到了相同的结果。

【讨论】：

不幸的是 :hidden: 选项不会跳过编译，它只会隐藏文档树中的链接（以防我想手动添加链接）。但是 Sphinx 仍然会编译文档，如果我输入它们的 URL，它们肯定是可以访问的。因此，编译时间并没有减少，这是我的目标，在大项目中尤其重要。还是谢谢！

【解决方案2】：

看来我可能已经找到了接近解决方案的东西（迄今为止最接近的）。它包括将.. 不缩进，即与toctree 指令处于同一级别。例如，我得到这样的东西：

.. toctree::
   
   Title 1 <file1>
   Title 2 <file2>
   Title 4 <file4>

.. the comment starts here
   Title 3 <file3>
   Title 5 <file5>
   etc

有了这个，我能得到的“评论/取消评论”的最佳方法是选择目标行并将其分别拖放到已评论/未评论的区域中。

【讨论】：