How to comment out a toctree entry with Sphinx?

Question

I am new to Sphinx and I don't seem to find the way to achieve this. I want to be able to quickly comment/uncomment single toctree entries as I progress, without having to remove the line. I use to do this in Latex to reduce the compilation time while my project is still in progress.

For instance, I'd like to achieve something like this:

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

What is the right way to do it?

Answer 1

It seems I might have found something close to a solution (the closest so far). It consists of putting the .. unindented, that is, at the same level as the toctree directive. For instance, I get something like this:

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

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

And having this, the best approach to 'comment/uncomment' I can get is by selecting the target line and drag&droping it into the commented/uncommented area, respectively.

Answer 2

Have you tried using the :hidden: option under the toctree directive? I image you'd need to have two separate toctree directives to achieve this though:

.. toctree::

    visiblefile1
    visiblefile2

.. toctree::
    :hidden:

    hiddenfile1
    hiddenfile2

See also sphinx-doc.org.

Perhaps this achieves acceptable results. Its not exactly commenting/uncommenting, but it achieves the same result.