4

I'm using a readthedocs.org instance on my localhost to build HTML documentation from my github repo and I would like to be able to do the following.

Currently I have a list of files being read by using toctree's glob feature like this:

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

     *

But I need to avoid certain files to be listed in my toc, eg:

Test_Manuals.rst
Test_Process.rst
Test_Users.rst
Testing.rst       <--- Only this file should appear in the toctree, all others are listed inside this one 
Testing_on_test_dot_spy.rst

I have tried adding a :hidden: below the :glob: section but it just hides everything.

I have looked into as much documentation I could find but nowhere I have found an example when these two options are used together.

Any idea how to achieve this?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Ricardo Vercesi
  • 71
  • 2
  • 5
  • Can you just simple contstruct toctree manually instead of using *? In the worst case you need to write a custom script snippet which outputs .rst itself :( – Mikko Ohtamaa Dec 02 '13 at 22:53
  • I want to allow developers to edit docs in github and have not to worry about toctree. It should use :glob: to index all available files but I want to hide some specific ones. – Ricardo Vercesi Dec 03 '13 at 14:38
  • Maintaining manual doc tree is the easiest option in this case. – Mikko Ohtamaa Dec 03 '13 at 14:54

1 Answers1

4

I'm relatively new to Sphinx, so perhaps this is terrible Sphinx-etiquette, but I found this gave the desired behaviour without any warnings:

.. toctree::
  :glob:

  dir_to_glob/*

.. toctree::
  :hidden:

  dir_to_glob/file_to_hide

Throwing in a second toctree seems to overwrite how to handle file_to_hide without messing up anything in the glob. In this way you only need to maintain a "to exclude" list (which for me is small, and sounds like it may be for your case as well.)

lhuber
  • 1,452
  • 1
  • 10
  • 13
  • This doesn't work in my scenario: my top-level toctree in `index.rst` contains `foo`, and `foo.rst` has your two-toctree thing in it. When I make html, `index.html` displays its toctree, and it contains all of the stuff that was in the full wildcard, not wildcard-minus-specifics. Edit: Putting the hidden toctree first didn't fix it either. – Claire Nielsen Jan 23 '18 at 19:12