docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs

docs/toctree_filter.py

@@ -0,0 +1,43 @@
+# Based on https://stackoverflow.com/a/46600038 with some modifications
+import re
+from sphinx.directives.other import TocTree
+from sphinx.util.nodes import explicit_title_re
+from sphinx.util import docname_join
+
+def setup(app):
+    app.add_directive('toctree', TocTreeFilt, override=True)
+
+
+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('^\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
+