From 4c310da88ed6e637107f37d5eb51e39bc25916e2 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Fri, 10 Mar 2023 13:25:18 -0800 Subject: [PATCH 1/4] docs: Remove "CSV" from our example of providing extra data via TSV These examples may have used CSV at one point, but now the whole section is focused around TSV. --- docs/advanced-functionality/drag-drop-csv-tsv.rst | 12 ++++++------ .../{csv-extra-data-2.png => extra-data-2.png} | Bin docs/assets/{csv-extra-data.png => extra-data.png} | Bin 3 files changed, 6 insertions(+), 6 deletions(-) rename docs/assets/{csv-extra-data-2.png => extra-data-2.png} (100%) rename docs/assets/{csv-extra-data.png => extra-data.png} (100%) diff --git a/docs/advanced-functionality/drag-drop-csv-tsv.rst b/docs/advanced-functionality/drag-drop-csv-tsv.rst index cf1a11cb4..eb7866253 100644 --- a/docs/advanced-functionality/drag-drop-csv-tsv.rst +++ b/docs/advanced-functionality/drag-drop-csv-tsv.rst @@ -20,10 +20,10 @@ A TSV file as follows can be dragged onto `nextstrain.org/zika Date: Fri, 10 Mar 2023 12:20:49 -0800 Subject: [PATCH 2/4] docs: Restore literal tabs to the TSV examples in the rST source These were inadvertently lost in "Convert markdown pages to reStructuredText" (7b8e45e2) which converted them to spaces. Note that these tabs still get expanded to spaces when rendering the rST to HTML, and thus copying the example from the HTML page to paste into a file will not produce a TSV. I'll address this in a subsequent commit. --- .../drag-drop-csv-tsv.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/advanced-functionality/drag-drop-csv-tsv.rst b/docs/advanced-functionality/drag-drop-csv-tsv.rst index eb7866253..109f75a9e 100644 --- a/docs/advanced-functionality/drag-drop-csv-tsv.rst +++ b/docs/advanced-functionality/drag-drop-csv-tsv.rst @@ -14,11 +14,11 @@ A TSV file as follows can be dragged onto `nextstrain.org/zika Date: Fri, 10 Mar 2023 13:27:57 -0800 Subject: [PATCH 3/4] docs: Restore literal tabs to the TSV examples in the rendered HTML Using the literalinclude directive to include an external file preserves literal tabs (unless the tab-width option is used to expand them). This resolves the copy and paste issue noted in "docs: Restore literal tabs to the TSV examples in the rST source" (1275eb3e). --- .../drag-drop-csv-tsv.rst | 18 ++++-------------- docs/assets/extra-data-2.tsv | 5 +++++ docs/assets/extra-data.tsv | 5 +++++ 3 files changed, 14 insertions(+), 14 deletions(-) create mode 100644 docs/assets/extra-data-2.tsv create mode 100644 docs/assets/extra-data.tsv diff --git a/docs/advanced-functionality/drag-drop-csv-tsv.rst b/docs/advanced-functionality/drag-drop-csv-tsv.rst index 109f75a9e..e20c3b6ed 100644 --- a/docs/advanced-functionality/drag-drop-csv-tsv.rst +++ b/docs/advanced-functionality/drag-drop-csv-tsv.rst @@ -12,13 +12,8 @@ Example: A TSV file as follows can be dragged onto `nextstrain.org/zika `__ to add a "secret" color-by: -.. code:: text - - strain secret - USVI/19/2016 A - USVI/28/2016 B - USVI/41/2016 C - USVI/42/2016 C +.. literalinclude:: ../assets/extra-data.tsv + :language: text .. figure:: ../assets/extra-data.png :alt: Auspice with extra data shown via TSV @@ -27,13 +22,8 @@ A TSV file as follows can be dragged onto `nextstrain.org/zika Date: Fri, 10 Mar 2023 13:38:58 -0800 Subject: [PATCH 4/4] docs: Render example TSV files as tables and provide download links This makes the TSV examples more readable on the page (i.e. the columns line up unlike the raw TSV) while still retaining the ability for a reader to get a copy of the example file to tinker with. We could use the tab-width option of the literalinclude directive to line up the columns, but that would break the ability to copy/paste the contents into a new TSV file, as the tabs get expanded to spaces when tab-width is used. --- .../drag-drop-csv-tsv.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/advanced-functionality/drag-drop-csv-tsv.rst b/docs/advanced-functionality/drag-drop-csv-tsv.rst index e20c3b6ed..56004db4d 100644 --- a/docs/advanced-functionality/drag-drop-csv-tsv.rst +++ b/docs/advanced-functionality/drag-drop-csv-tsv.rst @@ -10,20 +10,26 @@ The general format is compatible with other popular tools such as `MicroReact `__ to add a "secret" color-by: +A :download:`small TSV file <../assets/extra-data.tsv>` with the following data: -.. literalinclude:: ../assets/extra-data.tsv - :language: text +.. csv-table:: + :file: ../assets/extra-data.tsv + :delim: tab + +can be dragged onto `nextstrain.org/zika `_ to add a "secret" color-by: .. figure:: ../assets/extra-data.png :alt: Auspice with extra data shown via TSV Auspice with extra data shown via TSV -A more complex metadata file may look like the following, which makes use of additional features available. This defines colours for the metadata (e.g. ``A`` is yellow, ``B`` is orange) as well as associating strains with (made up) geographic coordinates. +A :download:`more complex TSV file <../assets/extra-data-2.tsv>` can add more data to make use of additional features available: + +.. csv-table:: + :file: ../assets/extra-data-2.tsv + :delim: tab -.. literalinclude:: ../assets/extra-data-2.tsv - :language: text +This defines colours for the metadata (e.g. ``A`` is yellow, ``B`` is orange) as well as associating strains with (made up) geographic coordinates. When dragged onto `nextstrain.org/zika`_, it looks like: .. figure:: ../assets/extra-data-2.png :alt: Auspice with extra data shown via TSV