doc: custom list filter directive

Custom directive that allows for creation of lists where the content can be filtered based on target.

Closes IDF-1385

docs/conf_common.py

@@ -53,6 +53,7 @@ extensions = ['breathe',
 
               'extensions.html_redirects',
               'extensions.toctree_filter',
+              'extensions.list_filter',
 
               'idf_extensions.include_build_file',
               'idf_extensions.link_roles',

docs/en/contribute/add-ons-reference.rst

@@ -71,6 +71,9 @@ These are Sphinx extensions developed for IDF that don't rely on any IDF-docs-sp
 :idf_file:`docs/extensions/toctree_filter.py`
     Sphinx extensions overrides the ``:toctree:`` directive to allow filtering entries based on whether a tag is set, as ``:tagname: toctree_entry``. See the Python file for a more complete description.
 
+:idf_file:`docs/extensions/list_filter.py`
+    Sphinx extensions that provides a ``.. list::`` directive that allows filtering of entries in lists based on whether a tag is set, as ``:tagname: - list content``. See the Python file for a more complete description.
+
 :idf_file:`docs/extensions/html_redirects.py`
     During documentation lifetime some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt`
 

docs/en/contribute/documenting-code.rst

@@ -267,7 +267,7 @@ Example:
 
 This functionality is provided by the `Sphinx selective exclude <https://github.com/pfalcon/sphinx_selective_exclude>`_ extension.
 
-The :TARGET: role is used for excluding content from a table of content tree. For example:
+The '':TARGET:'' role is used for excluding content from a table of content tree. For example:
 
 .. code-block:: none
 
@@ -281,6 +281,18 @@ When building the documents, Sphinx will use the above mentioned directive and r
 
 .. note:: If excluding an entire document from the toctree based on targets, it's necessary to also update the ``exclude_patterns`` list in :idf_file:`docs/conf_common.py` to exclude the file for other targets, or a Sphinx warning "WARNING: document isn't included in any toctree" will be generated..
 
+If you need to exclude content inside a list or bullet points then this should be done by using the '':TARGET:'' role inside the ''.. list:: '' directive.
+
+.. code-block:: none
+
+    .. list::
+    
+        :esp32: - ESP32 specific content
+        :esp32s2: - ESP32 S2 specific content
+        - Common bullet point
+        - Also common bullet point
+
+
 Substitution macros
 """""""""""""""""""
 When you need to refer to the chip's name, toolchain name, path or other common names that depend on the target type you can consider using the substitution macros supplied by :idf_file:`docs/idf_extensions/format_idf_target.py`.

docs/extensions/list_filter.py

@@ -0,0 +1,59 @@
+import re
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+def setup(app):
+    app.add_directive('list', ListFilter)
+
+    return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
+
+
+class ListFilter(Directive):
+    """
+    Provides a list implementation directive that support clauses of the kind
+
+    .. list::
+
+        - Content
+        :filter: - Content
+        - Content
+
+    Where the :filter: part becomes selective to only include the content if
+    one of the provided tags is set, same as the logic used by the "only" directive.
+
+    The directive also works for numbered list.
+
+    """
+    RE_PATTERN = re.compile(r'^\s*:(.+?):\s*(.+)$')
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        # Raise an error if the directive does not have contents.
+        self.assert_has_content()
+
+        # Remove all list entries that should not be on display
+        env = self.state.document.settings.env
+        filt_data = [self.filter_entry(env, e) for e in self.content.data if e is not None]
+
+        # Clean up deleted values from content
+        self.content.data = [data for data in filt_data if data is not None]
+        self.content.items = [items for data, items in zip(filt_data, self.content.items) if data is not None]
+
+        # Parse the filtered content and return the new node
+        node = nodes.paragraph()
+        self.state.nested_parse(self.content, self.content_offset, node)
+
+        return [node]
+
+    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