diff --git a/CHANGELOG.md b/CHANGELOG.md index 21d18e66..6ee72434 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/how-to/create-data-tables.rst b/docs/how-to/create-data-tables.rst new file mode 100644 index 00000000..1187e71e --- /dev/null +++ b/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 ` and :ref:`tables in MyST `. + +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 + ``` diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index c6ad305f..9c561c1c 100644 --- a/docs/how-to/index.rst +++ b/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 diff --git a/docs/reference/myst-syntax-reference.md b/docs/reference/myst-syntax-reference.md index 29dea71e..2d790e04 100644 --- a/docs/reference/myst-syntax-reference.md +++ b/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} diff --git a/docs/reference/rst-syntax-reference.rst b/docs/reference/rst-syntax-reference.rst index 7f364a2f..fd66c2f2 100644 --- a/docs/reference/rst-syntax-reference.rst +++ b/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 ----- diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index 738011e8..c2e0d5d6 100644 --- a/docs/reuse/links.txt +++ b/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