docs: add a how-to guide for data tables

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * Changes metrics script to a less brittle Python script
 * Introduce guidelines for adding diagrams-as-code
+* Introduce guidelines for rendering CSV data as tables
 * Introduce guidelines for pulling in docstrings using Sphinx `autodoc` extension
 * Introduce guidelines for using custom base templates
 

docs/how-to/create-data-tables.rst

@@ -0,0 +1,135 @@
+.. _create-data-tables:
+
+Create data tables
+===================
+
+The starter pack can render comma-separated values (CSV) data as tables.
+
+For other table types, see :ref:`tables in reStructuredText <style-guide-tables>` and :ref:`tables in MyST <myst_style_guide_tables>`.
+
+Create a table from inline data
+-------------------------------
+
+If you have a small amount of CSV data, you can include the data in the doc source. For example:
+
+.. tab-set::
+
+   .. tab-item:: Table
+
+      .. csv-table::
+         :header: "Animal", "Number of legs", "Size"
+
+         "Worm", 0, "Small"
+         "Penguin", 2, "Medium"
+         "Horse", 4, "Large"
+         "Ant", 6, "Small"
+         "Octopus", 8, "Medium"
+
+   .. tab-item:: reST
+
+      .. code-block:: rst
+
+         .. csv-table::
+            :header: "Animal", "Number of legs", "Size"
+
+            "Worm", 0, "Small"
+            "Penguin", 2, "Medium"
+            "Horse", 4, "Large"
+            "Ant", 6, "Small"
+            "Octopus", 8, "Medium"
+
+      If the table needs it, customize the column widths, character encoding, and so on, as described in the `csv-table reference`_.
+
+   .. tab-item:: MyST
+
+      .. code-block:: none
+
+         ```{csv-table}
+         :header: "Animal", "Number of legs", "Size"
+
+         "Worm", 0, "Small"
+         "Penguin", 2, "Medium"
+         "Horse", 4, "Large"
+         "Ant", 6, "Small"
+         "Octopus", 8, "Medium"
+         ```
+
+      If the table needs it, customize the column widths, character encoding, and so on, as described in the `csv-table reference (MyST)`_.
+
+Create a table from a CSV file
+------------------------------
+
+If you have a large amount of CSV data, or the data is generated by an automated process, you can include the data from a file. For example:
+
+.. tab-set::
+
+   .. tab-item:: Table
+
+      .. csv-table::
+         :header: "Animal", "Number of legs", "Size"
+
+         "Worm", 0, "Small"
+         "Penguin", 2, "Medium"
+         "Horse", 4, "Large"
+         "Ant", 6, "Small"
+         "Octopus", 8, "Medium"
+
+   .. tab-item:: reST
+
+      .. code-block:: rst
+
+         .. csv-table::
+            :file: /reuse/animals.csv
+            :header-rows: 1
+
+   .. tab-item:: MyST
+
+      .. code-block:: none
+
+         ```{csv-table}
+         :file: /reuse/animals.csv
+         :header-rows: 1
+         ```
+
+   .. tab-item:: ``docs/reuse/animals.csv``
+
+      .. code-block:: none
+
+         "Animal", "Number of legs", "Size"
+         "Worm", 0, "Small"
+         "Penguin", 2, "Medium"
+         "Horse", 4, "Large"
+         "Ant", 6, "Small"
+         "Octopus", 8, "Medium"
+
+Create an interactive table
+---------------------------
+
+The `Sphinx DataTables`_ extension enables interactive tables. Users can sort columns and filter rows. For examples, see the extension's documentation.
+
+The extension isn't available by default in the starter pack.
+
+To include the extension in your documentation, add ``sphinx-datatables`` to ``docs/requirements.txt``. Then add ``sphinx_datatables`` to the ``extensions`` list in ``docs/conf.py``.
+
+Make a table interactive by adding a special CSS class to the directive:
+
+.. tab-set::
+
+   .. tab-item:: reST
+
+      .. code-block:: rst
+
+         .. csv-table::
+            :class: sphinx-datatable
+            :file: /reuse/animals.csv
+            :header-rows: 1
+
+   .. tab-item:: MyST
+
+      .. code-block:: none
+
+         ```{csv-table}
+         :class: sphinx-datatable
+         :file: /reuse/animals.csv
+         :header-rows: 1
+         ```

docs/how-to/index.rst

@@ -24,12 +24,15 @@ Set up, configure, upgrade, and customize your project to keep it organized and
 Optional features and workflows
 -------------------------------
 
-As your documentation grows, you may need additional features and workflows to support richer content and more advanced use cases, such as diagrams as code, automated API references, and interactive data tables.
+As your documentation grows, you may need more advanced features to support richer content. This can include diagrams as code, automated API references, and data tables.
+
+While some of these features are available by default in the starter pack, others may require additional extensions. The following guides will help you get started:
 
 .. toctree::
    :maxdepth: 1
 
    diagrams-as-code-mermaid
+   create-data-tables
    import-docstrings-with-autodoc
    openapi
    custom-templates

docs/reference/myst-syntax-reference.md

@@ -456,6 +456,8 @@ Adhere to the following conventions:
     : Definition
 ````
 
+(myst_style_guide_tables)=
+
 ## Tables
 
 You can use standard Markdown tables. However, using the reST [list table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) syntax is usually much easier.
@@ -504,6 +506,10 @@ See [list tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#l
 ```
 ````
 
+### Data tables
+
+The starter pack can render CSV data as tables. See {ref}`create-data-tables`.
+
 ## Notes
 
 `````{list-table}

docs/reference/rst-syntax-reference.rst

@@ -523,6 +523,8 @@ Definition lists
        Term 2:
          Definition
 
+.. _style-guide-tables:
+
 Tables
 ------
 
@@ -579,6 +581,11 @@ See `list tables`_ for reference.
       * - Cell 3
         - Cell 4
 
+Data tables
+~~~~~~~~~~~
+
+The starter pack can render CSV data as tables. See :ref:`create-data-tables`.
+
 Notes
 -----
 

docs/reuse/links.txt

@@ -2,6 +2,8 @@
 .. _Canonical Reference Library: https://library.canonical.com/
 .. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx
 .. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log
+.. _csv-table reference: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
+.. _csv-table reference (MyST): https://mystmd.org/guide/directives#directive-csv-table
 .. _Diátaxis: https://diataxis.fr/
 .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
 .. _Example product documentation repository: https://github.com/canonical/example-product-documentation
@@ -26,6 +28,7 @@
 .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 .. _`Sphinx`: https://www.sphinx-doc.org/
 .. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html
+.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/
 .. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/
 .. _Sphinx documentation starter pack:
 .. _Sphinx documentation starter pack repository: https://github.com/canonical/starter-pack