docs: Improve TSV examples #1638
Conversation
These examples may have used CSV at one point, but now the whole section is focused around TSV.
These were inadvertently lost in "Convert markdown pages to reStructuredText" (7b8e45e) 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.
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" (1275eb3).
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.
There was a problem hiding this comment.
Slick! I learn something new about Sphinx every time you make a PR. Looks like I should be referencing Sphinx docs more, or just browsing it in general...
| USVI/28/2016 B | ||
| USVI/41/2016 C | ||
| USVI/42/2016 C | ||
| strain secret |
There was a problem hiding this comment.
Oops, thanks for catching this.
😊 \o/ Yeah, I think browsing official docs, in addition to using them for reference and search, is really underrated. The main reason is that browsing lets you build a mental index of what's available (and what's not), which is very useful before the reference/search phase of doc usage. (I'm not alone either.) ⁂ ⁂ ⁂ I'm going to wait a bit for @jameshadfield to chime in here since he had previous thoughts on these examples. |
|
@jameshadfield Thanks for the 👀. Agreed good to reinforce these are plain text files! I think the download links maybe do that a bit less than inlined verbatim blocks, but also think that the improved reading experience of table + download is probably worth it. |
See commit messages.
Related issue(s)
#1588, #1588 (comment)
Testing