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
This commit is contained in:
Marius Vikhammer 2020-02-13 17:14:39 +08:00
parent 8d8337e80c
commit 63b76a9d90
4 changed files with 76 additions and 1 deletions

View file

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

View file

@ -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`

View file

@ -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`.

View file

@ -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