Documentation/sphinx/rstFlatTable.py

2 # -*- coding: utf-8; mode: python -*-
6     flat-table
9     Implementation of the ``flat-table`` reST-directive.
14     The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
15     the ``list-table`` with some additional features:
17     * *column-span*: with the role ``cspan`` a cell can be extended through
20     * *row-span*: with the role ``rspan`` a cell can be extended through
24       right side of that table-row.  With Option ``:fill-cells:`` this behavior
30     * header-rows:   [int] count of header rows
31     * stub-columns:  [int] count of stub columns
33     * fill-cells:    instead of autospann missing cells, insert missing cells
47 from docutils import nodes
57 # (Documentation/books/kernel-doc-HOWTO).
72     app.add_directive("flat-table", FlatTable)
106 class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
107 class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
114     u"""FlatTable (``flat-table``) directive"""
119         , 'header-rows': directives.nonnegative_int
120         , 'stub-columns': directives.nonnegative_int
122         , 'fill-cells' : directives.flag }
129                 nodes.literal_block(self.block_text, self.block_text),
134         node = nodes.Element()          # anonymous container for parsing
140         # SDK.CONSOLE()  # print --> tableNode.asdom().toprettyxml()
150     u"""Builds a table from a double-stage list"""
165         stub_columns = self.directive.options.get('stub-columns', 0)
166         header_rows  = self.directive.options.get('header-rows', 0)
168         table = nodes.table()
169         tgroup = nodes.tgroup(cols=len(colwidths))
174             colspec = nodes.colspec(colwidth=colwidth)
176             # absence of rowspan (observed by the html buidler, the docutils-xml
178             # no table directive (except *this* flat-table) which allows to
179             # define coexistent of rowspan and stubs (there was no use-case
180             # before flat-table). This should be reviewed (later).
183                 stub_columns -= 1
185         stub_columns = self.directive.options.get('stub-columns', 0)
188             thead = nodes.thead()
193         tbody = nodes.tbody()
202         row = nodes.row()
213             entry = nodes.entry(**attributes)
221             , nodes.literal_block(self.directive.block_text
229         if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
249         * Autospan or fill (option ``fill-cells``) missing cells on the right
250           side of the table-row
282         # re-calculate the max columns.
291         if 'fill-cells' in self.directive.options:
295             x =  self.max_cols - len(row)
297                 if row[-1] is None:
298                     row.append( ( x - 1, 0, []) )
300                     cspan, rspan, content = row[-1]
301                     row[-1] = (cspan + x, rspan, content)
304                     row.append( (0, 0, nodes.comment()) )
322             retVal = retVal[:-2]
324         retVal = retVal[:-2]
334         for child in rowItem:
335             if (isinstance(child , nodes.comment)
336                 or isinstance(child, nodes.system_message)):
338             elif isinstance(child , nodes.target):
339                 target = child
340             elif isinstance(child, nodes.bullet_list):
342                 cell = child
350                 'two-level bullet list expected, but row %s does not '
351                 'contain a second-level bullet list.'