-
Notifications
You must be signed in to change notification settings - Fork 7.2k
/
toctree_filter.py
43 lines (30 loc) · 1.46 KB
/
toctree_filter.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Based on https://stackoverflow.com/a/46600038 with some modifications
import re
from sphinx.directives.other import TocTree
def setup(app):
app.add_directive('toctree', TocTreeFilt, override=True)
return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
class TocTreeFilt(TocTree):
"""
Override normal toctree directive to support clauses of the kind
:filter: Name <link>
Where the :filter: part becomes selective to only include the document if
one of the provided tags is set, same as the logic used by the "only" directive.
If no :filter: is supplied, works the same as default Sphinx :toctree:
Note that excluding via filter doesn't prevent Sphinx from finding these .rst files
when it scan the src/ directory, so it's also necessary to make sure that the files
are covered by the exclude_patterns list in conf.py
"""
RE_PATTERN = re.compile(r'^\s*:(.+?):\s*(.+)$')
def run(self):
# Remove all TOC entries that should not be on display
env = self.state.document.settings.env
self.content = [self.filter_entry(env, e) for e in self.content if e is not None]
return super(TocTreeFilt, self).run()
def filter_entry(self, env, entry):
m = self.RE_PATTERN.match(entry)
if m is not None:
tag_filter, entry = m.groups()
if not env.app.builder.tags.eval_condition(tag_filter):
return None
return entry