0

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Martí
  • 571
  • 6
  • 17
  • 1
    That works for me. I just get a warning: `WARNING: toctree contains reference to nonexisting document '.. file3'`, and the docs build. If you still see a built page, then you first need to `make clean` to delete the originally built file. – Steve Piercy Apr 03 '21 at 10:24
  • Yeah, I had noted that, but in one hand I do not think it is the real solution (because I can get many warnings making my compiling output not neat) but more importantly, when using a custom caption (e.g. ``Title 3 ``) then it does not work at all. It will compile the document file3 (which is what I want to avoid) and it will show the link as ".. Title 3" on the generated html. – Martí Apr 08 '21 at 10:03

2 Answers2

0

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.

Pierce Devol
  • 125
  • 7
  • 1
    Unfortunately the :hidden: option does not skip the compilation, it only hides the link in the doctree (in case I want to add the link manually). But Sphinx still compiles the documents and they are definitely accessible if I type their URL. Therefore, the compilation time is not reduced, which is my goal, and particularly important in big projects. Thanks anyway! – Martí Apr 08 '21 at 09:15
0

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.

Martí
  • 571
  • 6
  • 17