Captions for tables and improved cross references #10282
Description
Description
Hi there! Long time user, first time contributor. This is a question/comment about tables and captions.
Issue
The Documentation Guidelines, in the section on "Tables" in the "Writing Guidelines", suggest that tables cannot have captions. Here is the example:
.. _my_drawn_table:
+---------------+--------------------+
| Windows | macOS |
+---------------+--------------------+
| |win| | |osx| |
+---------------+--------------------+
| and of course not to forget |nix| |
+------------------------------------+
My drawn table, mind you this is unfortunately not regarded as a caption
You can reference it like this: my_drawn_table_.Issue: The link text (e.g. "my_drawn_table") does not actually appear in the visible text of the table. Hence, only the hyperlink can direct readers to the referenced table.
For example, consider Section 4.2 of the "Gentle Introduction to GIS," which includes a reference to a table, with the link text appearing as: "table_house_attributes." The text "table_house_attributes" does not appear in the actual table. The caption below the table, moreover, is difficult to distinguish from ordinary paragraphs.
Possible solution: Table directives
As you may already know, however, it is possible to add a caption to a table by using an explicit table directive with a caption as an argument (this also works for list-table and csv-table directives). Additionally, if you use a Sphinx :numref: directive to cross reference the table, then my_drawn_table will be replaced by the table number (e.g. "Table 2.1").
For example:
.. _my_drawn_table:
.. table:: My drawn table (this is the caption)
+---------------+--------------------+
| Windows | macOS |
+---------------+--------------------+
| |win| | |osx| |
+---------------+--------------------+
| and of course not to forget |nix| |
+------------------------------------+
You can reference it like this: :numref:`my_drawn_table`.The final line will appear like the following (with a hyperlink, of course):
"You can reference it like this: Table 2.1."
These kinds of captions are actually used elsewhere in the documentation. See, for example, Section 7.1.1. of Chapter 7, Visualizing Maps, in the User Guide.
Question/Comment
Would explicit table directives (as above) help to improve the clarity of references to tables in the documentation?
If these changes are of interest, I'd be happy to open a pull request as a demonstration.