please document the rst-class and/or cssclass directive #8220
Milestone
Comments
zzzeek
changed the title
5 tasks
jfbu
added a commit
to jfbu/sphinx
that referenced
this issue
Aug 11, 2022
Commit sphinx-doc@bb859c6 already improved a bit, this finishes it (as :rst:dir:`rst-class` was actually not linking to anywhere).
jfbu
added a commit
to jfbu/sphinx
that referenced
this issue
Aug 14, 2022
This is a combination of 28 commits... - Simplify a bit a conditional in the longtable template This also puts the target for a longtable with a label but no caption above the toprule for better hyperlinking (testing shows hyperlink target can not end up alone at bottom of previous page). - Refactor and trim doc about LaTeX tables... to make room for more, later - Enlarge allowed syntax for colour assignments via 'sphinxsetup' - latex_table_style new configuration value and coloured rows For the user interface tried to look for inspiration in https://docutils.sourceforge.io/docs/user/config.html#table-style which mentions booktabs and borderless. They also mention captionbelow which we can implement later, now that architecture is here. They don't mention coloured rows. - Test on our own document... looks fine! - Update LaTeX table tests and templates Modify longtable templates to put LaTeX macros each on its line Table body insertion without removing previous EOL may give output which contain some empty lines but longtable defines \par token to be same as \empty. - Work-around an incompatibility of \cline with row colours, improve docs - Reverse priority of classes to allow overruling booktabs by standard after parsing source but before letting LaTeX writer act - Closes sphinx-doc#8220 Commit sphinx-doc@bb859c6 already improved a bit, this finishes it (as :rst:dir:`rst-class` was actually not linking to anywhere). - Update CHANGES for PR sphinx-doc#10759 - Let booktabs style defaults to *not* using \cmidrule. They actually don't make much sense there, as all \hline's are removed. - Enhance customizability at LaTeX code level (via code executed prior to table rendering, e.g. from a container class environment). - Patch booktabs \cmidrule, as if it used via \sphinxcline, there is a vertical space problem in case of there are two in the same row due to booktabs \futurelet not knowing \sphinxcline - Add \sphinxnorowcolor which allows construct such as this one in a tabularcolumns directive: >{\columncolor{blue}\sphinxnorowcolor} else LaTeX always overrides column colour by row colour - Add TableMergeColorHeader, TableMergeColorOdd, TableMergeColorEven so single-row merged cells can be styled especially - Extend row colours to all header rows not only the first one (all header rows will share same colour settings) - Auto-adjust to a no '|'-colspec for optimal handling of merged cell - Add \sphinxcolorblend - Needed to also detect if a '|' is in tabularcolumns, tests updated - Fix refactoring in this series which broke table.colsep update - Add test which would have shown regression regarding table.colsep - Fix another regression regarding \sphinxcline + booktabs Can not add test for that, because it shows only after PDF build. - Final testing and code comments update
jfbu
added a commit
to jfbu/sphinx
that referenced
this issue
Aug 14, 2022
This is a combination of 28 commits... - Simplify a bit a conditional in the longtable template This also puts the target for a longtable with a label but no caption above the toprule for better hyperlinking (testing shows hyperlink target can not end up alone at bottom of previous page). - Refactor and trim doc about LaTeX tables... to make room for more, later - Enlarge allowed syntax for colour assignments via 'sphinxsetup' - latex_table_style new configuration value and coloured rows For the user interface tried to look for inspiration in https://docutils.sourceforge.io/docs/user/config.html#table-style which mentions booktabs and borderless. They also mention captionbelow which we can implement later, now that architecture is here. They don't mention coloured rows. - Test on our own document... looks fine! - Update LaTeX table tests and templates Modify longtable templates to put LaTeX macros each on its line Table body insertion without removing previous EOL may give output which contain some empty lines but longtable defines \par token to be same as \empty. - Work-around an incompatibility of \cline with row colours, improve docs - Reverse priority of classes to allow overruling booktabs by standard after parsing source but before letting LaTeX writer act - Closes sphinx-doc#8220 Commit sphinx-doc@bb859c6 already improved a bit, this finishes it (as :rst:dir:`rst-class` was actually not linking to anywhere). - Update CHANGES for PR sphinx-doc#10759 - Let booktabs style defaults to *not* using \cmidrule. They actually don't make much sense there, as all \hline's are removed. - Enhance customizability at LaTeX code level (via code executed prior to table rendering, e.g. from a container class environment). - Patch booktabs \cmidrule, as if it used via \sphinxcline, there is a vertical space problem in case of there are two in the same row due to booktabs \futurelet not knowing \sphinxcline - Add \sphinxnorowcolor which allows construct such as this one in a tabularcolumns directive: >{\columncolor{blue}\sphinxnorowcolor} else LaTeX always overrides column colour by row colour - Add TableMergeColorHeader, TableMergeColorOdd, TableMergeColorEven so single-row merged cells can be styled especially - Extend row colours to all header rows not only the first one (all header rows will share same colour settings) - Auto-adjust to a no '|'-colspec for optimal handling of merged cell - Add \sphinxcolorblend - Needed to also detect if a '|' is in tabularcolumns, tests updated - Fix refactoring in this series which broke table.colsep update - Add test which would have shown regression regarding table.colsep - Fix another regression regarding \sphinxcline + booktabs Can not add test for that, because it shows only after PDF build. - Final testing and code comments update
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Restructured text has a class directive that lets you add a css class to an element. This won't work in Sphinx because it conflicts with the default domain's "class", usually py:class.
Sphinx has already found a solution for this, which is that it redefines docutils Class under cssclass and rst-class.
I found these by source-code diving and purposely breaking docutils "Class" and following where the import errors led me. Otherwise, "rst-class" and "cssclass" are not documented at all except for a passing, unlinked mention of rst-class here.
the "rst-class" directive should be documented at the very least in the domains chapter so that those of us wondering why we can't use RST
.. class::know where to look for the alternative.The text was updated successfully, but these errors were encountered: