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
 
 ### Added

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

@@ -0,0 +1,139 @@
+.. _create-data-tables:
+
+Create data tables
+===================
+
+The starter pack can render comma-separated values (CSV) data as tables.
+
+For other types of table, 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:: none
+
+         .. csv-table::
+            :header: "Animal", "Number of legs", "Size"
+
+            "Worm", 0, "Small"
+            "Penguin", 2, "Medium"
+            "Horse", 4, "Large"
+            "Ant", 6, "Small"
+            "Octopus", 8, "Medium"
+
+      See `csv-table (reST)`_.
+
+   .. 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"
+         ```
+
+      See `csv-table (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:: none
+
+         .. csv-table::
+            :file: /reuse/animals.csv
+            :header-rows: 1
+
+      See `csv-table (reST)`_.
+
+   .. tab-item:: MyST
+
+      .. code-block:: none
+
+         ```{csv-table}
+         :file: /reuse/animals.csv
+         :header-rows: 1
+         ```
+
+      See `csv-table (MyST)`_.
+
+   .. 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`_ extenstion enables your tables to become interactive. Your readers will be able to 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``.
+
+After including the extension, use the ``sphinx-datatable`` class to make tables interactive. For example:
+
+.. tab-set::
+
+   .. tab-item:: reST
+
+      .. code-block:: none
+
+         .. 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,11 +24,14 @@ 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
+   openapi

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 (MyST): https://mystmd.org/guide/directives#directive-csv-table
+.. _csv-table (reST): https://docutils.sourceforge.io/docs/ref/rst/directives.html#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