diff --git a/doc/src/_ext/table_from_list.py b/doc/src/_ext/table_from_list.py new file mode 100644 index 0000000000..44c85fc378 --- /dev/null +++ b/doc/src/_ext/table_from_list.py @@ -0,0 +1,56 @@ +from docutils import nodes +from sphinx.util.docutils import SphinxDirective +from docutils.nodes import Element, Node +from typing import Any, Dict, List +from sphinx import addnodes +from sphinx.util import logging + +class TableFromList(SphinxDirective): + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'columns': int, + } + + def run(self) -> List[Node]: + ncolumns = self.options.get('columns', 2) + node = addnodes.compact_paragraph() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + reporter = self.state.document.reporter + return [reporter.warning('.. table_from_list content is not a list', line=self.lineno)] + fulllist = node.children[0] + table = nodes.table() + tgroup = nodes.tgroup(cols=ncolumns) + table += tgroup + + for i in range(ncolumns): + tgroup += nodes.colspec(colwidth=1) + + tbody = nodes.tbody() + tgroup += tbody + current_row = nodes.row() + + for idx, cell in enumerate(fulllist.children): + if len(current_row.children) == ncolumns: + tbody += current_row + current_row = nodes.row() + entry = nodes.entry() + current_row += entry + if len(cell.children) > 0: + entry += cell.children[0] + + tbody += current_row + return [table] + +def setup(app): + app.add_directive("table_from_list", TableFromList) + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/utils/sphinx-config/conf.py b/doc/utils/sphinx-config/conf.py index 70a96e1614..0b6dfcca2d 100644 --- a/doc/utils/sphinx-config/conf.py +++ b/doc/utils/sphinx-config/conf.py @@ -20,6 +20,7 @@ import os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) +sys.path.append(os.path.join(os.path.dirname(__file__), '../../src/_ext')) # -- General configuration ------------------------------------------------ @@ -30,7 +31,9 @@ import os # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.mathjax', 'sphinx.ext.imgmath' + 'sphinx.ext.mathjax', + 'sphinx.ext.imgmath', + 'table_from_list', ] # 2017-12-07: commented out, since this package is broken with Sphinx 16.x # yet we can no longer use Sphinx 15.x, since that breaks with