I want to do multiple versions of a documentation, which differ in the sections that are included. To achieve this I would usually use either the only directive or the ifconfig extension. However, I cannot use any of those in combination with the toctree directive.
What I basically want is something like this:
.. toctree:: :maxdepth: 2 intro strings datatypes numeric .. only:: university complex Is there a way to do that?
As far as I know there is no way to do what you would like. I have been struggling with the same issue, see https://github.com/sphinx-doc/sphinx/issues/1717.
The reason is that Sphinx process all lines contained in a toctree node as pure text.
I see two alternatives:
you can extend the toctree including an option that contains the expression to be evaluated
.. toctree: :condition: expression file1 and then you customize the doctree resolve event.
you can use text substitutions on the raw text defining your own tags. you can do that implementing an event handler for the source-read event. For instance $$condition$$ could contain the condition to be evaluated, while $$$ the end of the block, i.e.
.. toctree: file1 $$mycondition$$ file2 $$$ Depending on mycondition, you can remove the following block lines.
Number 3 is quite simple, while to me number 2 is the most elegant.
My solution is to place the conditional content in a separate directory 'intern' and using a tag 'internal'.
In conf.py I added the lines
if tags.has('internal'): exclude_patters = ['_build'] else: exclude_patterns = ['_build', 'intern*'] Now when I pass the 'internal' flag on the command line I get all, otherwise everything except the contents in the intern directory.
The tag internal can be used in combination with only.
The ToC contains references to intern/somedoc and they are included or skipped as required. I do get a number of warnings about missing pages but those can be silenced.
A very simple solution is to maintain two separate index files under different names. You can specify which index file to use by default in conf.py and override it for a special build using -D master_doc=alternate-index on the sphinx-build command line.
My previous answer fails if you have hierarchies of table of contents so I wrote a simple toctree-filt directive that is able to filter entries based on a prefix to the entry. For example, given a toctree-filt directive like
.. toctree-filt:: :maxdepth: 1 user-manual :internal:supervisor-api :draft:new-feature :erik:erik-maths api and setting the exclusion list to ['draft','erik'] will result in an effective toctree that looks like
.. toctree-filt:: :maxdepth: 1 user-manual supervisor-api api Add the following lines to your conf.py:
sys.path.append(os.path.abspath('../sphinx-ext/')) extensions = ['toctree_filter'] toc_filter_exclude = ['draft','erik'] Put the following code in /sphinx_ext next to your /source directory:
import re from sphinx.directives.other import TocTree def setup(app): app.add_config_value('toc_filter_exclude', [], 'html') app.add_directive('toctree-filt', TocTreeFilt) return {'version': '1.0.0'} class TocTreeFilt(TocTree): """ Directive to notify Sphinx about the hierarchical structure of the docs, and to include a table-of-contents like tree in the current document. This version filters the entries based on a list of prefixes. We simply filter the content of the directive and call the super's version of run. The list of exclusions is stored in the **toc_filter_exclusion** list. Any table of content entry prefixed by one of these strings will be excluded. If `toc_filter_exclusion=['secret','draft']` then all toc entries of the form `:secret:ultra-api` or `:draft:new-features` will be excuded from the final table of contents. Entries without a prefix are always included. """ hasPat = re.compile('^\s*:(.+):(.+)$') # Remove any entries in the content that we dont want and strip # out any filter prefixes that we want but obviously don't want the # prefix to mess up the file name. def filter_entries(self, entries): excl = self.state.document.settings.env.config.toc_filter_exclude filtered = [] for e in entries: m = self.hasPat.match(e) if m != None: if not m.groups()[0] in excl: filtered.append(m.groups()[1]) else: filtered.append(e) return filtered def run(self): # Remove all TOC entries that should not be on display self.content = self.filter_entries(self.content) return super().run() Now just change your existing toctree directives to toctree-filt and you are good to roll. Note that Sphinx will post errors because it will find files that are not included in the document. Not sure how to fix that.