.. include:: ../../../sphinx_refs.txt


.. index::
   pair: Sphinx ; flat-table
   ! flat-table


.. _rst_flat_tables:
.. _rst_flat_table:

=================================================
flat-table (needs linuxdoc extension, 2016-2017)
=================================================

.. seealso::

   - https://github.com/return42/linuxdoc
   - `LinuxDoc flat table`_
   - https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#rest-flat-table


.. contents::
   :depth: 3


Requirements
=============

We have to :ref:`install linuxdoc extension <install_linux_doc>`.


flat-table
===========

The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar
to the ``list-table`` with some additional features:

* *column-span*: with the role ``cspan`` a cell can be extended through
  additional columns

* *row-span*: with the role ``rspan`` a cell can be extended through
  additional rows

* *auto-span* rightmost cell of a table row over the missing cells on the right
  side of that table-row.  With Option ``:fill-cells:`` this behavior can
  changed from *auto span* to *auto fill*, which automatically inserts (empty)
  cells instead of spanning the last cell.

options:
  :header-rows:   [int] count of header rows
  :stub-columns:  [int] count of stub columns
  :widths:        [[int] [int] ... ] widths of columns
  :fill-cells:    instead of auto-span missing cells, insert missing cells

roles:
  :cspan: [int] additional columns (*morecols*)
  :rspan: [int] additional rows (*morerows*)

The example below shows how to use this markup.  The first level of the staged
list is the *table-row*. In the *table-row* there is only one markup allowed,
the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).      
 
.. code-block:: rst

   .. flat-table:: table title
      :header-rows: 2
      :stub-columns: 1
      :widths: 1 1 1 1 2

      * - :rspan:`1` head / stub
        - :cspan:`3` head 1.1-4

      * - head 2.1
        - head 2.2
        - head 2.3
        - head 2.4

      * .. row body 1 / this is a comment

        - row 1
        - :rspan:`2` cell 1-3.1
        - cell 1.2
        - cell 1.3
        - cell 1.4

      * .. Comments and targets are allowed on *table-row* stage.
        .. _`row body 2`:

        - row 2
        - cell 2.2
        - :rspan:`1` :cspan:`1`
          cell 2.3 with a span over

          * col 3-4 &
          * row 2-3

      * - row 3
        - cell 3.2

      * - row 4
        - cell 4.1
        - cell 4.2
        - cell 4.3
        - cell 4.4

      * - row 5
        - cell 5.1 with automatic span to rigth end

      * - row 6
        - cell 6.1
        - ..
      

.. flat-table:: table title
   :header-rows: 2
   :stub-columns: 1
   :widths: 1 1 1 1 2

   * - :rspan:`1` head / stub
     - :cspan:`3` head 1.1-4

   * - head 2.1
     - head 2.2
     - head 2.3
     - head 2.4

   * .. row body 1 / this is a comment

     - row 1
     - :rspan:`2` cell 1-3.1
     - cell 1.2
     - cell 1.3
     - cell 1.4

   * .. Comments and targets are allowed on *table-row* stage.
     .. _`row body 2`:

     - row 2
     - cell 2.2
     - :rspan:`1` :cspan:`1`
       cell 2.3 with a span over

       * col 3-4 &
       * row 2-3

   * - row 3
     - cell 3.2

   * - row 4
     - cell 4.1
     - cell 4.2
     - cell 4.3
     - cell 4.4

   * - row 5
     - cell 5.1 with automatic span to rigth end

   * - row 6
     - cell 6.1
     - ..