Figures currently have a caption below the figure. This patch adds a config option that allows placement above the figure.
Documentation is added, but no test. Tips on how to progress would be appreciated.
+1 for adding a new option to control the position. I'm also okay to add a directive option instead. Addition to this, I'll add an option for table caption after this discussion.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thank you for the patch.
Some considerations about the context:
Changing the order of figure and caption in the document tree would require a change of the formal document tree definition. Currently, we have in docutils.dtd:
We would also need to ensure and test that all writers can process the doctree with changed order.
But maybe there is no need to go this route.
Placement of table and figure captions may be left to the stylesheet or writer. The doctree only stores a class value. With HTML5/CSS3 this is possible (and for tables already implemented).
(Per definition, writers may ignore class values, if they are hard to implement or not applicable for the
produced output format.)
Try rst2html5.py with
..table:: table test
:class:captionbelow numbered booktabs
===== =====
A not A
===== =====
Caption placement for tables and figures should be configurable on several levels:
Document-wide:
* The default given by the stylesheet or document class.
* Configuration file setting.
* Command line option.
Per object
* directive option
To override stylesheet defaults or config file settings, we would need 4 simple command line options
(tablecaptionabove, tablecaptionbelow, figurecaptionabove, figurecaptionbelow) or 2 selector-options
(tablecaption=above/below, figurecaption=above/below or something similar.
The current implementation is a config file setting and command line option "table-style" that adds the
content to the class values of all table elements. As the caption is above the table by default, currently only the "captionbelow" class value is cared for. However, a custom style sheet may also change the default and define a rule for "table.captionabove".
For figures, the situation is complicated by the "legend" that may follow the caption. Should the legend also move to the top? Or should the result of "figure caption above" be:
caption [figure]
legend
?
Changing the figure caption placement per CSS is already possible with a flex-box
(if there is no legend or the legend shall move together with the caption).
Currently the legend is nested in the <caption> tag. If we want the legend always below,
it should follow the caption element instead.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
+1 for adding a new option to control the position. I'm also okay to add a directive option instead. Addition to this, I'll add an option for table caption after this discussion.
Thank you for the patch.
Some considerations about the context:
Changing the order of figure and caption in the document tree would require a change of the formal document tree definition. Currently, we have in docutils.dtd:
We would also need to ensure and test that all writers can process the doctree with changed order.
But maybe there is no need to go this route.
Placement of table and figure captions may be left to the stylesheet or writer. The doctree only stores a class value. With HTML5/CSS3 this is possible (and for tables already implemented).
(Per definition, writers may ignore class values, if they are hard to implement or not applicable for the
produced output format.)
Try rst2html5.py with
Caption placement for tables and figures should be configurable on several levels:
Document-wide:
* The default given by the stylesheet or document class.
* Configuration file setting.
* Command line option.
Per object
* directive option
To override stylesheet defaults or config file settings, we would need 4 simple command line options
(tablecaptionabove, tablecaptionbelow, figurecaptionabove, figurecaptionbelow) or 2 selector-options
(tablecaption=above/below, figurecaption=above/below or something similar.
The current implementation is a config file setting and command line option "table-style" that adds the
content to the class values of all table elements. As the caption is above the table by default, currently only the "captionbelow" class value is cared for. However, a custom style sheet may also change the default and define a rule for "table.captionabove".
For figures, the situation is complicated by the "legend" that may follow the caption. Should the legend also move to the top? Or should the result of "figure caption above" be:
caption
[figure]
legend
?
Changing the figure caption placement per CSS is already possible with a flex-box
(if there is no legend or the legend shall move together with the caption).
Currently the legend is nested in the
<caption>tag. If we want the legend always below,it should follow the caption element instead.