sphinxlatextables.sty

%% TABLES (WITH SUPPORT FOR MERGED CELLS OF GENERAL CONTENTS)
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatextables.sty}[2022/08/10 tables]%

% Provides support for this output mark-up from Sphinx latex writer
% and table templates:
%
% - the tabulary and longtable environments from the eponymous packages
% - the varwidth environment
% - the >{} etc mark-up possible in tabularcolumns is from array package
%     which is loaded by longtable and tabulary
% - \X, \Y, T column types; others (L, C, R, J) are from tabulary package
% - \sphinxaftertopcaption
% - \sphinxatlongtableend
% - \sphinxatlongtablestart
% - \sphinxattableend
% - \sphinxattablestart
% - \sphinxcapstartof
% - \sphinxcolwidth
% - \sphinxlongtablecapskipadjust
% - \sphinxmultirow
% - \sphinxstartmulticolumn
% - \sphinxstopmulticolumn
% - \sphinxtablestrut
% - \sphinxthecaptionisattop
% - \sphinxthelongtablecaptionisattop
% - \sphinxhline
% - \sphinxcline
% - \sphinxtoprule
% - \sphinxmidrule
% - \sphinxbottomrule
% - \sphinxarrayrulewidth
% - \sphinxthistablewithglobalstyle
% - \sphinxthistablewithbooktabsstyle
% - \sphinxthistablewithborderlessstyle
% - \sphinxthistablewithstandardstyle
% - \sphinxthistablewithcolorrowsstyle
% - \sphinxthistablewithnocolorrowsstyle
% - \sphinxtableatstartofbodyhook
% - \sphinxtableafterendhook
%
% Executes \RequirePackage for:
%
% - tabulary
% - longtable
% - varwidth
% - colortbl
%
% Extends tabulary and longtable via patches and custom macros to support
% merged cells possibly containing code-blocks in complex tables

\RequirePackage{tabulary}
% tabulary has a bug with its re-definition of \multicolumn in its first pass
% which is not \long. But now Sphinx does not use LaTeX's \multicolumn but its
% own macro. Hence we don't even need to patch tabulary. See
% sphinxpackagemulticell.sty
% X or S (Sphinx) may have meanings if some table package is loaded hence
% \X was chosen to avoid possibility of conflict
\def\sphinxarrayrulewidth{\arrayrulewidth}% will be set to \z@ if booktabs option
\newcolumntype{\X}[2]{p{\dimexpr
      (\linewidth-\sphinxarrayrulewidth)*#1/#2-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}}
\newcolumntype{\Y}[1]{p{\dimexpr
      #1\dimexpr\linewidth-\sphinxarrayrulewidth\relax-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}}
% using here T (for Tabulary) feels less of a problem than the X could be
\newcolumntype{T}{J}%
% For tables allowing pagebreaks
\RequirePackage{longtable}
% User interface to set-up whitespace before and after tables:
\newcommand*\sphinxtablepre {0pt}%
\newcommand*\sphinxtablepost{\medskipamount}%
% Space from caption baseline to top of table or frame of literal-block
\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}%
% as one can not use \baselineskip from inside longtable (it is zero there)
% we need \sphinxbaselineskip, which defaults to \baselineskip
\def\sphinxbaselineskip{\baselineskip}%
% The following is to ensure that, whether tabular(y) or longtable:
% - if a caption is on top of table:
%   a) the space between its last baseline and the top rule of table is
%      exactly \sphinxbelowcaptionspace
%   b) the space from last baseline of previous text to first baseline of
%      caption is exactly \parskip+\baselineskip+ height of a strut.
%   c) the caption text will wrap at width \LTcapwidth (4in)
% - make sure this works also if "caption" package is loaded by user
%   (with its width or margin option taking place of \LTcapwidth role)
% TODO: obtain same for caption of literal block: a) & c) DONE, b) TO BE DONE
%
% To modify space below such top caption, adjust \sphinxbelowcaptionspace
% To add or remove space above such top caption, adjust \sphinxtablepre:
%   notice that \abovecaptionskip, \belowcaptionskip, \LTpre are **ignored**
% A. Table with longtable
\def\sphinxatlongtablestart
   {\par
    \vskip\parskip
    \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
    \vbox{}% get correct baseline from above
    \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
    \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}%
   }%
% Compatibility with caption package
\def\sphinxthelongtablecaptionisattop{%
    \spx@ifcaptionpackage{\noalign{\vskip-\belowcaptionskip}}{}%
}%
% Achieves exactly \sphinxbelowcaptionspace below longtable caption
\def\sphinxlongtablecapskipadjust
   {\dimexpr-\dp\strutbox
            -\spx@ifcaptionpackage{\abovecaptionskip}{\sphinxbaselineskip}%
            +\sphinxbelowcaptionspace\relax}%
\def\sphinxatlongtableend{\@nobreakfalse % latex3/latex2e#173
    \prevdepth\z@\vskip\sphinxtablepost\relax}%
% B. Table with tabular or tabulary
\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
\let\sphinxattableend\sphinxatlongtableend
% This is used by tabular and tabulary templates
\newcommand*\sphinxcapstartof[1]{%
   \vskip\parskip
   \vbox{}% force baselineskip for good positioning by capstart of hyperanchor
   % hyperref puts the anchor 6pt above this baseline; in case of caption
   % this baseline will be \ht\strutbox above first baseline of caption
   \def\@captype{#1}%
   \capstart
% move back vertically, as tabular (or its caption) will compensate
   \vskip-\baselineskip\vskip-\parskip
}%
\def\sphinxthecaptionisattop{% locate it after \sphinxcapstartof
    \spx@ifcaptionpackage
      {\caption@setposition{t}%
       \vskip\baselineskip\vskip\parskip % undo those from \sphinxcapstartof
       \vskip-\belowcaptionskip          % anticipate caption package skip
       % caption package uses a \vbox, not a \vtop, so "single line" case
       % gives different result from "multi-line" without this:
       \nointerlineskip
      }%
      {}%
}%
\def\sphinxthecaptionisatbottom{% (not finalized; for template usage)
    \spx@ifcaptionpackage{\caption@setposition{b}}{}%
}%
% The aim of \sphinxcaption is to apply to tabular(y) the maximal width
% of caption as done by longtable
\def\sphinxtablecapwidth{\LTcapwidth}%
\newcommand\sphinxcaption{\@dblarg\spx@caption}%
\long\def\spx@caption[#1]#2{%
   \noindent\hb@xt@\linewidth{\hss
      \vtop{\@tempdima\dimexpr\sphinxtablecapwidth\relax
% don't exceed linewidth for the caption width
            \ifdim\@tempdima>\linewidth\hsize\linewidth\else\hsize\@tempdima\fi
% longtable ignores \abovecaptionskip/\belowcaptionskip, so do the same here
            \abovecaptionskip\sphinxabovecaptionskip % \z@skip
            \belowcaptionskip\sphinxbelowcaptionskip % \z@skip
            \caption[{#1}]%
               {\strut\ignorespaces#2\ifhmode\unskip\@finalstrut\strutbox\fi}%
           }\hss}%
   \par\prevdepth\dp\strutbox
}%
\def\sphinxabovecaptionskip{\z@skip}% Do not use! Flagged for removal
\def\sphinxbelowcaptionskip{\z@skip}% Do not use! Flagged for removal
% This wrapper of \abovecaptionskip is used in sphinxVerbatim for top
% caption, and with another value in sphinxVerbatimintable
% TODO: To unify space above caption of a code-block with the one above
%       caption of a table/longtable, \abovecaptionskip must not be used
%       This auxiliary will get renamed and receive a different meaning
%       in future.
\def\spx@abovecaptionskip{\abovecaptionskip}%
% Achieve \sphinxbelowcaptionspace below a caption located above a tabular
% or a tabulary
\newcommand\sphinxaftertopcaption
{%
   \spx@ifcaptionpackage
     {\par\prevdepth\dp\strutbox\nobreak\vskip-\abovecaptionskip}{\nobreak}%
   \vskip\dimexpr\sphinxbelowcaptionspace\relax
   \vskip-\baselineskip\vskip-\parskip
}%
% varwidth is crucial for our handling of general contents in merged cells
\RequirePackage{varwidth}
% but addition of a compatibility patch with hyperref is needed
% (tested with varwidth v 0.92  Mar 2009)
\AtBeginDocument {%
    \let\@@vwid@Hy@raisedlink\Hy@raisedlink
    \long\def\@vwid@Hy@raisedlink#1{\@vwid@wrap{\@@vwid@Hy@raisedlink{#1}}}%
    \edef\@vwid@setup{%
      \let\noexpand\Hy@raisedlink\noexpand\@vwid@Hy@raisedlink % HYPERREF !
      \unexpanded\expandafter{\@vwid@setup}}%
}%

% NOTA BENE: since the multicolumn and multirow code was written Sphinx
% decided to prefix non public internal macros by \spx@ and in fact all
% such macros here should now be prefixed by \spx@table@, but doing the
% update is delayed to later. (written at 5.2.0)

%%%%%%%%%%%%%%%%%%%%%
% --- MULTICOLUMN ---
% standard LaTeX's \multicolumn
% 1. does not allow verbatim contents,
% 2. interacts very poorly with tabulary.
%
% It is needed to write own macros for Sphinx: to allow code-blocks in merged
% cells rendered by tabular/longtable, and to allow multi-column cells with
% paragraphs to be taken into account sanely by tabulary algorithm for column
% widths.
%
% This requires quite a bit of hacking. First, in Sphinx, the multi-column
% contents will *always* be wrapped in a varwidth environment. The issue
% becomes to pass it the correct target width. We must trick tabulary into
% believing the multicolumn is simply separate columns, else tabulary does not
% incorporate the contents in its algorithm. But then we must clear the
% vertical rules...
%
% configuration of tabulary
\setlength{\tymin}{3\fontcharwd\font`0 }% minimal width of "squeezed" columns
\setlength{\tymax}{10000pt}% allow enough room for paragraphs to "compete"
% we need access to tabulary's final computed width. \@tempdima is too volatile
% to hope it has kept tabulary's value when \sphinxcolwidth needs it.
\newdimen\sphinx@TY@tablewidth
\def\tabulary{%
  \def\TY@final{\sphinx@TY@tablewidth\@tempdima\tabular}%
  \let\endTY@final\endtabular
  \TY@tabular}%
% next hack is needed only if user has set latex_use_latex_multicolumn to True:
% it fixes tabulary's bug with \multicolumn defined "short" in first pass. (if
% upstream tabulary adds a \long, our extra one causes no harm)
\def\sphinx@tempa #1\def\multicolumn#2#3#4#5#6#7#8#9\sphinx@tempa
   {\def\TY@tab{#1\long\def\multicolumn####1####2####3{\multispan####1\relax}#9}}%
\expandafter\sphinx@tempa\TY@tab\sphinx@tempa
%
% TN. 1: as \omit is never executed, Sphinx multicolumn does not need to worry
% like standard multicolumn about |l| vs l|. On the other hand it assumes
% columns are separated by a | ... (if not it will add extraneous
% \arrayrulewidth space for each column separation in its estimate of available
% width).
%
%   EDIT: Sphinx 5.2.0 uses \sphinxarrayrulewidth which is \z@ if booktabs
%   option has been used.  Do not mix booktabs option with usage of | in
%   tabularcolumns directive.
%
% TN. 1b: as Sphinx multicolumn uses neither \omit nor \span, it can not
% (easily) get rid of extra macros from >{...} or <{...} between columns. At
% least, it has been made compatible with colortbl's \columncolor.
%
% TN. 2: tabulary's second pass is handled like tabular/longtable's single
% pass, with the difference that we hacked \TY@final to set in
% \sphinx@TY@tablewidth the final target width as computed by tabulary. This is
% needed only to handle columns with a "horizontal" specifier: "p" type columns
% (inclusive of tabulary's LJRC) holds the target column width in the
% \linewidth dimension.
%
% TN. 3: use of \begin{sphinxmulticolumn}...\end{sphinxmulticolumn} mark-up
% would need some hacking around the fact that groups can not span across table
% cells (the code does inserts & tokens, see TN1b). It was decided to keep it
% simple with \sphinxstartmulticolumn...\sphinxstopmulticolumn.
%
% MEMO about nesting: if sphinxmulticolumn is encountered in a nested tabular
% inside a tabulary it will think to be at top level in the tabulary. But
% Sphinx generates no nested tables, and if some LaTeX macro uses internally a
% tabular this will not have a \sphinxstartmulticolumn within it!
%
% 5.2.0 adds a check for multirow as for such complex multi-column multi-row
% cells we must deactivate also a row colour.
\def\sphinxstartmulticolumn#1#2{%
    \ifx\sphinxmultirow#2% #2 is either \sphinxmultirow or \begin
    \def\spx@table@hackCT@inmergedcell{\spx@table@hackCT@nocolor}%
    \fi
    \sphinx@startmulticolumn{#1}#2%
}%
\def\sphinx@startmulticolumn{%
    \ifx\equation$% $ tabulary's first pass
        \expandafter\sphinx@TYI@start@multicolumn
    \else % either not tabulary or tabulary's second pass
        \expandafter\sphinx@start@multicolumn
    \fi
}%
\def\sphinxstopmulticolumn{%
    \ifx\equation$% $ tabulary's first pass
        \expandafter\sphinx@TYI@stop@multicolumn
    \else % either not tabulary or tabulary's second pass
        \ignorespaces
    \fi
}%
\def\sphinx@TYI@start@multicolumn#1{%
    % use \gdef always to avoid stack space build up
    \gdef\sphinx@tempa{#1}\begingroup\setbox\z@\hbox\bgroup
}%
\def\sphinx@TYI@stop@multicolumn{\egroup % varwidth was used with \tymax
    \xdef\sphinx@tempb{\the\dimexpr\wd\z@/\sphinx@tempa}% per column width
    \endgroup
    \expandafter\sphinx@TYI@multispan\expandafter{\sphinx@tempa}%
}%
\def\sphinx@TYI@multispan #1{%
    \kern\sphinx@tempb\ignorespaces % the per column occupied width
    \ifnum#1>\@ne % repeat, taking into account subtleties of TeX's & ...
      \expandafter\sphinx@TYI@multispan@next\expandafter{\the\numexpr#1-\@ne\expandafter}%
    \fi
}%
\def\sphinx@TYI@multispan@next{&\relax\sphinx@TYI@multispan}%
%
% Now the branch handling either the second pass of tabulary or the single pass
% of tabular/longtable. This is the delicate part where we gather the
% dimensions from the p columns either set-up by tabulary or by user p column
% or Sphinx \X, \Y columns. The difficulty is that to get the said width, the
% template must be inserted (other hacks would be horribly complicated except
% if we rewrote crucial parts of LaTeX's \@array !) and we can not do
% \omit\span like standard \multicolumn's easy approach. Thus we must cancel
% the \vrule separators. Also, perhaps the column specifier is of the l, c, r
% type, then we attempt an ad hoc rescue to give varwidth a reasonable target
% width.
\def\sphinx@start@multicolumn#1{%
    \gdef\sphinx@multiwidth{0pt}\gdef\sphinx@tempa{#1}\sphinx@multispan{#1}%
}%
\def\sphinx@multispan #1{%
    \ifnum#1=\@ne\expandafter\sphinx@multispan@end
            \else\expandafter\sphinx@multispan@next
    \fi {#1}%
}%
\def\sphinx@multispan@next #1{%
    % trick to recognize L, C, R, J or p, m, b type columns
    \ifdim\baselineskip>\z@
       \gdef\sphinx@tempb{\linewidth}%
    \else
    % if in an l, r, c type column, try and hope for the best
       \xdef\sphinx@tempb{\the\dimexpr(\ifx\TY@final\@undefined\linewidth\else
            \sphinx@TY@tablewidth\fi-\sphinxarrayrulewidth)/\sphinx@tempa
            -\tw@\tabcolsep-\sphinxarrayrulewidth\relax}%
    \fi
    \noindent\kern\sphinx@tempb\relax
    \xdef\sphinx@multiwidth
           {\the\dimexpr\sphinx@multiwidth+\sphinx@tempb+\tw@\tabcolsep+\sphinxarrayrulewidth}%
    % simulate the \vline added width
    \spx@table@fakevline
    % prevent column colours to interfere with our multi-column
    % but allow row colour; sadly we can't recover a \cellcolor as it has
    % not be seen yet at this stage, which is preparatory to the varwidth
    % environment execution... and background colour panels are injected
    % during this stage... as we did not use \omit based mechanism...
    \spx@table@hackCT@inmergedcell&\relax
    % repeat
    \expandafter\sphinx@multispan\expandafter{\the\numexpr#1-\@ne}%
}%
\def\sphinx@multispan@end#1{%
    % first, trace back our steps horizontally
    \noindent\kern-\dimexpr\sphinx@multiwidth\relax
    % and now we set the final computed width for the varwidth environment
    \ifdim\baselineskip>\z@
       \xdef\sphinx@multiwidth{\the\dimexpr\sphinx@multiwidth+\linewidth}%
    \else
       \xdef\sphinx@multiwidth{\the\dimexpr\sphinx@multiwidth+
         (\ifx\TY@final\@undefined\linewidth\else
          \sphinx@TY@tablewidth\fi-\sphinxarrayrulewidth)/\sphinx@tempa
          -\tw@\tabcolsep-\sphinxarrayrulewidth\relax}%
    \fi
    % we need to remove colour set-up also for last cell of the multi-column
    \aftergroup\spx@table@hackCT@inmergedcell
}%
\newcommand*\sphinxcolwidth[2]{%
  % this dimension will always be used for varwidth, and serves as maximum
  % width when cells are merged either via multirow or multicolumn or both,
  % as always their contents is wrapped in varwidth environment.
  \ifnum#1>\@ne % multi-column (and possibly also multi-row)
  % we wrote our own multicolumn code especially to handle that (and allow
  % verbatim contents)
   \ifx\equation$%$
       \tymax % first pass of tabulary (cf MEMO above regarding nesting)
   \else % the \@gobble thing is for compatibility with standard \multicolumn
       \sphinx@multiwidth\@gobble{#1/#2}%
   \fi
  \else % single column multirow
   \ifx\TY@final\@undefined % not a tabulary.
    \ifdim\baselineskip>\z@
        % in a p{..} type column, \linewidth is the target box width
        \linewidth
    \else
        % l, c, r columns. Do our best.
        \dimexpr(\linewidth-\sphinxarrayrulewidth)/#2-
                \tw@\tabcolsep-\sphinxarrayrulewidth\relax
    \fi
   \else % in tabulary
    \ifx\equation$%$% first pass
        \tymax % it is set to a big value so that paragraphs can express themselves
    \else
     % second pass.
     \ifdim\baselineskip>\z@
         \linewidth % in a L, R, C, J column or a p, \X, \Y ...
     \else
         % we have hacked \TY@final to put in \sphinx@TY@tablewidth the table width
         \dimexpr(\sphinx@TY@tablewidth-\sphinxarrayrulewidth)/#2-
                 \tw@\tabcolsep-\sphinxarrayrulewidth\relax
     \fi
    \fi
   \fi
  \fi
}%
% fallback default in case user has set latex_use_latex_multicolumn to True:
% \sphinxcolwidth will use this only inside LaTeX's standard \multicolumn
\def\sphinx@multiwidth #1#2{\dimexpr % #1 to gobble the \@gobble (!)
    (\ifx\TY@final\@undefined\linewidth\else\sphinx@TY@tablewidth\fi
     -\sphinxarrayrulewidth)*#2-\tw@\tabcolsep-\sphinxarrayrulewidth\relax}%

% \spx@table@fakevline
% packages like colortbl add group levels, we need to "climb back up" to be
% able to hack the \vline and also the colortbl inserted tokens. The hack
% induces an empty space of the width corresponding to a \vline.
% (5.2.0 sets \sphinxarrayrulewidth to expand to \z@ if booktabs option has been
%  made use of, the \arrayrulewidth\z@ serves then nothing but shoud not hurt).
\def\spx@table@fakevline{\ifnum\currentgrouptype=6\relax
    \kern\sphinxarrayrulewidth\arrayrulewidth\z@\else\aftergroup\spx@table@fakevline\fi}%

% hacking around colour matters
% Sphinx 1.6 comment:
% It turns out \CT@row@color is not expanded contrarily to \CT@column@color
% during LaTeX+colortbl preamble preparation, hence it would be possible for
% \CT@setup to discard only the column color and choose to obey or not
% row color and cell color. It would even be possible to propagate cell color
% to row color for the duration of the Sphinx multicolumn... the (provisional?)
% choice has been made to cancel the colortbl colours for the multicolumn
% duration.
% Sphinx 5.2.0 comment:
% - colortbl has no mechanism to disable colour background in a given cell:
%   \cellcolor triggers one more \color, but has no possibility to revert
%   a previously emitted \color, only to override it via an additional \color
% - prior to <5.2.0, Sphinx did not officially support colour in tables,
%   but it did have a mechanism to protect merged cells from being partly
%   covered by colour panels at various places.  At 5.2.0 this mechanism
%   is relaxed a bit to allow row colour for a single-row merged cell
%   which is mostly useful for a cell taking all table width I guess.
%
% \spx@table@hackCT@inmergedcell
% \spx@table@hackCT@nocolor
% \spx@table@hackCT@norowcolor
%
% \let\spx@original@CT@setup\CT@setup is done after the loading of colortbl
% package
%
% inmergedcell
\def\spx@table@hackCT@inmergedcell{\ifnum\currentgrouptype=6\relax
    \let\CT@setup\spx@CT@setup@inmergedcell
    \else\aftergroup\spx@table@hackCT@inmergedcell\fi
}%
\newif\ifspx@table@inmergedcell
\def\spx@CT@setup@inmergedcell #1\endgroup{%
    % - obey only row color and disable effect of \sphinxblendcolor
    % - turn on the inmergedcell boolean to signal to \CT@row@color
    \spx@original@CT@setup
    \spx@table@inmergedcelltrue % needed by \CT@row@color
    % deactivate effect of \sphinxcolorblend if it happened at all
    \ifdefined\blendcolors\blendcolors{}\fi
    \CT@row@color
    \CT@do@color
    \global\let\CT@cell@color\relax
    \endgroup
}%
%
% nocolor
\def\spx@table@hackCT@nocolor{\ifnum\currentgrouptype=6\relax
% sadly \CT@column@color is possibly already expanded so we can't
% simply do \let\CT@column@color\relax etc...
% admittedly we could perhaps hack \CT@color but well
    \let\CT@setup\spx@CT@setup@nocolor
    \else\aftergroup\spx@table@hackCT@nocolor\fi
}
\def\spx@CT@setup@nocolor#1\endgroup{%
        \global\let\CT@cell@color\relax
    % the above added at 5.2.0
    % else a \cellcolor added by a raw latex directive in the merged cell
    % will create color leak in cells to the right of the merged cell
    \endgroup}
%
% norowcolor
\def\spx@table@hackCT@norowcolor{%
% a bit easier although merged cells complicate the matter as they do need
% to keep the rowcolor; and we can't know yet if we are in a merged cell
    \ifnum\currentgrouptype=6\relax
       \ifx\CT@row@color\relax
       \else
           \let\spx@saved@CT@row@color\CT@row@color
           \def\CT@row@color{%
             \ifspx@table@inmergedcell\expandafter\spx@saved@CT@row@color\fi
           }%
       \fi
    \else\aftergroup\spx@table@hackCT@norowcolor\fi
}
%
% sphinxcolormix (commented-out)
% this works but then I found out about \blendcolors in xcolor doc, so I provided
% rather \sphinxcolorblend
% \@ifpackageloaded{xcolor}{%
% \def\spx@table@hackCT@colormix{%
%     \ifnum\currentgrouptype=6\relax
%      \ifx\CT@column@color\relax
%      \else
%        \ifx\CT@row@color\relax
%        \else
%            \let\spx@saved@CT@row@color\CT@row@color
%            \def\CT@row@color{%
%              \ifspx@table@inmergedcell
%                \expandafter\spx@saved@CT@row@color
%              \else
%                \colorlet{spxcolumncolor}{.}%
%                \spx@saved@CT@row@color
%                \colorlet{spxrowcolor}{.}%
%                \color{spxcolumncolor!\spx@colormixparam!spxrowcolor}%
%              \fi
%            }% patched \CT@row@color
%        \fi
%      \fi
%     \else
%       \aftergroup\spx@table@hackCT@colormix
%     \fi
% }%
% }{\let\spx@table@hackCT@colormix\@empty}% no-op if no xcolor as \colorlet needed
% \def\sphinxcolormix#1{\gdef\spx@colormixparam{#1}\spx@table@hackCT@colormix}
%
% \sphinxcolorblend
\@ifpackageloaded{xcolor}{%
\def\spx@table@hackCT@colorblend{%
    \ifnum\currentgrouptype=6\relax
        \expandafter\blendcolors\spx@colorblendparam
        % merged cells will do a \blendcolors{} to cancel the effet
        % we can not know here yet if in merged cell as the boolean
        % \ifspx@table@inmergedcell is not yet updated
    \else
      \aftergroup\spx@table@hackCT@colorblend
    \fi
}%
}{\let\spx@table@hackCT@colorblend\@empty}% defined to be no-op if no xcolor
\def\sphinxcolorblend#1{\gdef\spx@colorblendparam{{#1}}\spx@table@hackCT@colorblend}


%%%%%%%%%%%%%%%%%%
% --- MULTIROW ---
% standard \multirow
% 1. does not allow verbatim contents,
% 2. does not allow blank lines in its argument,
% 3. its * specifier means to typeset "horizontally" which is very
%    bad for paragraph content. 2016 version has = specifier but it
%    must be used with p type columns only, else results are bad,
% 4. it requires manual intervention if the contents is too long to fit
%    in the asked-for number of rows.
% 5. colour panels (either from \rowcolor or \columncolor) will hide
%    the bottom part of multirow text, hence manual tuning is needed
%    to put the multirow insertion at the _bottom_.
%
% The Sphinx solution consists in always having contents wrapped
% in a varwidth environment so that it makes sense to estimate how many
% lines it will occupy, and then ensure by insertion of suitable struts
% that the table rows have the needed height. The needed mark-up is done
% by LaTeX writer, which has its own id for the merged cells.
%
% The colour issue is "solved" by clearing colour panels in all cells,
% whether or not the multirow is single-column or multi-column.
%
% MEMO at 5.2.0: to allow a multirow cell in a single column to react to
% \columncolor correctly, it seems only way is that the contents
% are inserted by bottom cell (this is mentioned in multirow.sty doc, too).
% Sphinx could at Python level "move" the contents to that cell.  But the
% mechanism used here via \sphinxtablestrut to enlarge rows to make room for
% the contents if needed becomes more challenging yet, because \sphinxtablestrut
% mark-up will be parsed by TeX *before* it sees the contents of the merged
% cell.. So it seems the best way would be to actually store the contents into
% some owned-by-Sphinx box storage which needs to be globally allocated to
% that usage ; then we need multiple such boxes, say at least 5 to cover
% 99% or use case.  Or perhaps some trick with storing in a \vbox and recovering
% via some \vsplit but this becomes complicated... perhaps in future.
%
% In passing we obtain baseline alignements across rows (only if
% \arraystretch is 1, as LaTeX's does not obey \arraystretch in "p"
% multi-line contents, only first and last line...)
%
% TODO: examine the situation with \arraystretch > 1. The \extrarowheight
% is hopeless for multirow anyhow, it makes baseline alignment strictly
% impossible.
\newcommand\sphinxmultirow[2]{\begingroup
  % #1 = nb of spanned rows, #2 = Sphinx id of "cell", #3 = contents
  % but let's fetch #3 in a way allowing verbatim contents !
  \def\sphinx@nbofrows{#1}\def\sphinx@cellid{#2}%
  \afterassignment\sphinx@multirow\let\next=
}%
\def\sphinx@multirow {%
  \setbox\z@\hbox\bgroup\aftergroup\sphinx@@multirow\strut
}%
\def\sphinx@@multirow {%
% MEMO: we could check status of \CT@cell@color here, but unfortunately we
% can't know the exact height which will be covered by the cells in total
% (it may be more than our \box\z@ dimensions).  We could use an \fcolorbox
% wrapper on \box\z@ but this will not extend precisely to the bottom rule.
%
% Only solution if we want to obey a raw \cellcolor, or a \columncolor, seems
% to delay unboxing the gathered contents as part of the bottom row with
% a suitable verticale adjustement...
%
  % The contents, which is a varwidth environment, has been captured in
  % \box0 (a \hbox).
  % We have with \sphinx@cellid an assigned unique id. The goal is to give
  % about the same height to all the involved rows.
  % For this Sphinx will insert a \sphinxtablestrut{cell_id} mark-up
  % in LaTeX file and the expansion of the latter will do the suitable thing.
  \dimen@\dp\z@
  \dimen\tw@\ht\@arstrutbox
  \advance\dimen@\dimen\tw@
  \advance\dimen\tw@\dp\@arstrutbox
  \count@=\dimen@       % type conversion dim -> int
  \count\tw@=\dimen\tw@
  \divide\count@\count\tw@ % TeX division truncates
  \advance\dimen@-\count@\dimen\tw@
  % 1300sp is about 0.02pt. For comparison a rule default width is 0.4pt.
  % (note that if \count@ holds 0, surely \dimen@>1300sp)
  \ifdim\dimen@>1300sp \advance\count@\@ne \fi
  % now \count@ holds the count L of needed "lines"
  % and \sphinx@nbofrows holds the number N of rows
  % we have L >= 1 and N >= 1
  % if L is a multiple of N, ... clear what to do !
  % else write L = qN + r, 1 <= r < N and we will
  % arrange for each row to have enough space for:
  %     q+1 "lines" in each of the first r rows
  %       q "lines" in each of the (N-r) bottom rows
  % for a total of (q+1) * r + q * (N-r) = q * N + r = L
  % It is possible that q == 0.
  \count\tw@\count@
  % the TeX division truncates
  \divide\count\tw@\sphinx@nbofrows\relax
  \count4\count\tw@ % q
  \multiply\count\tw@\sphinx@nbofrows\relax
  \advance\count@-\count\tw@ % r
  \expandafter\xdef\csname sphinx@tablestrut_\sphinx@cellid\endcsname
     {\noexpand\sphinx@tablestrut{\the\count4}{\the\count@}{\sphinx@cellid}}%
  \dp\z@\z@
  % this will use the real height if it is >\ht\@arstrutbox
  \sphinxtablestrut{\sphinx@cellid}\box\z@
  \endgroup % group was opened in \sphinxmultirow
}%
\newcommand*\sphinxtablestrut[1]{%
  % #1 is a "cell_id", i.e. the id of a merged group of table cells
  \csname sphinx@tablestrut_#1\endcsname
}%
% LaTeX typesets the table row by row, hence each execution can do
% an update for the next row.
\newcommand*\sphinx@tablestrut[3]{\begingroup
  % #1 = q, #2 = (initially) r, #3 = cell_id, q+1 lines in first r rows
  % if #2 = 0, create space for max(q,1) table lines
  % if #2 > 0, create space for q+1 lines and decrement #2
  \leavevmode
  \count@#1\relax
  \ifnum#2=\z@
    \ifnum\count@=\z@\count@\@ne\fi
  \else
    % next row will be with a #2 decremented by one
    \expandafter\xdef\csname sphinx@tablestrut_#3\endcsname
      {\noexpand\sphinx@tablestrut{#1}{\the\numexpr#2-\@ne}{#3}}%
   \advance\count@\@ne
  \fi
  \vrule\@height\ht\@arstrutbox
        \@depth\dimexpr\count@\ht\@arstrutbox+\count@\dp\@arstrutbox-\ht\@arstrutbox\relax
        \@width\z@
  \endgroup
  % we need this to avoid colour panels hiding bottom parts of multirow text
  % whether they originate in \columncolor or \rowcolor (or even \cellcolor
  % even though it can be only in top cell, but we could hijack it).
  \spx@table@hackCT@nocolor
}%

%%%%%%%%%%%%%%%%%%
% --- STYLING ---
%

% the initialization macros executed before the table environments
% their scope is limited by a wrapper "savenotes" environment
%
% 0) color support is enacted via adding code to three hooks:
%    - \sphinxtabletoprulehook       (implicit from \sphinxtoprule expansion)
%    - \sphinxtableatstartofbodyhook (explicit from table templates)
%    - \sphinxtableafterendhook      (explicit from table templates)
%    additionally special adjustment must be made in \sphinxcline
%
% 1) we manage these three hooks in a way allowing a custom user extra wrapper
% environment from a container class to use them as entry point for some
% custom code.  The container code is done first, prior to table templates.
% So, the style macros will *prepend* the needed color-code to the existing
% custom user code, so the custom user code can override them.  The custom
% user code should not redefine any of the 3 \sphinxtable...hook macros via a
% \global\def, but their contents can use \gdef if this is the user intention,
% (attention that the hooks are executed from inside the table, except the
% afterend hook so probably the code in-there should use \noalign),
%
% 2) the table templates and LaTeX writer code make it so that only
% one of either
%      \sphinxthistablewithcolorrowsstyle,
% or   \sphinxthistablewithnocolorrowsstyle
% will be inserted explicitly depending on local :class: for table.
% The global 'colorrows' style in latex_table_style translates at bottom
% of this file into code for inserting \sphinxthistablewithcolorrowsstyle
% at end of \sphinxthistablewithglobalstyle.  So it is impossible
% to have first \sphinxthistablewithnocolorrowsstyle, then
% \sphinxthistablewithcolorrowsstyle.  Nevertheless we have written
% the code so that in this case colorrows would indeed activate (except
% if it was already executed before as it self-annihilates).

\let\sphinxtabletoprulehook      \@empty
\let\sphinxtableatstartofbodyhook\@empty
\let\sphinxtableafterendhook     \@empty

%
% Support for colour in table
%
% Core LaTeX package (very old, part of texlive-latex-base on Debian distr.)
% providing \columncolor, \rowcolor, \cellcolor and \arrayrulecolor.
\RequirePackage{colortbl}
\let\spx@original@CT@setup\CT@setup
%
% - passing option "table" to xcolor also loads colortbl but we needed to
%   load color or xcolor prior to the handling of the options
%
% - the \rowcolors command from [table]{xcolor} has various problems:
%
%   *  it is rigid and does not out-of-the-box allow a more complex scheme
%   such as colorA+colorB+colorC+colorB+colorC+colorB+colorC...  suitable to
%   distinguish a header row.
%
%   *  its code does not export the used colour, an information which we may
%   need for example to colourize the rule via \arrayrulecolor in the
%   appropriate manner, for example to colourize the booktabs induced vertical
%   whitespace to avoid gaps (if one wants to).
%
%   *  incompatibility with tabulary: the output depends on parity of total
%   number of rows!
%
%   *  problems with longtable: the caption will receive a background colour
%   panel, if we do not deactivate the \rowcolors action during definition of
%   the headers and footers; this requires extra mark-up.  Besides if we
%   deactivate using \hiderowcolors during header and footer formation, the
%   parity of the body rows is shifted, \rownum is even, not odd, at first body
%   row.  And setting \rownum at start of first body row is too late for
%   influencing the colour.
%
%   *  it has a global impact and must be reset at each table.  We can not
%   issue it only once and it provides no public interface (without @) to
%   cancel its effect conveniently (\hiderowcolors can only be used from
%   *inside* a table.)
%
%   *  its core mechanism which increments the row count is triggered
%   if a \cline is encountered... so this offsets the alternating colours...
%   ... or not if there are two \cline's in the row...
%   (as we will use same mechanism we have to correct this increment).
%
% So we need our own code.  And matters of longtable unfortunately force
% us to some addition to table template, simply hooking into in-place
% \sphinxtoprule etc mark-up is not enough.  After some hesitation and due
% to problems of the continuation hints of longtable we decide not to try
% for coloured headers (which would be fine with tabular and tabulary
% actually) except for the first header row via a \rowcolor, not via the
% \rowcolors-style hack into \CT@everycr.

% Provide \rownum and rownum LaTeX counter (code copied from colortbl v1.0f)
\ltx@ifundefined{rownum}{%
  \ltx@ifundefined{c@rownum}%
       {\newcount\rownum\let\c@rownum\rownum}%
       {\let\rownum\c@rownum}%
  }%
{\let\c@rownum\rownum}
\providecommand\therownum{\arabic{rownum}}

% extra overhang for color panels to avoid visual artifacts in pdf viewers
% (particularly if borderless)
\def\sphinxcolorpanelextraoverhang{0.1pt}

% set the colours according to row parity; a priori #1 is \rownum it is
% possible to set the colours, as in this macro code, from inside a
% (non-merged) cell (via commands inserted via raw directive), it will then
% influence the colours in its row starting from the cell.
\def\sphinxSwitchCaseRowColor#1{%
  \ifodd#1\relax
    \global\sphinxcolorlet{sphinxTableRowColor}{sphinxTableRowColorOdd}%
    \global\sphinxcolorlet{sphinxTableMergeColor}{\sphinxTableMergeColorOdd}%
  \else
    \global\sphinxcolorlet{sphinxTableRowColor}{sphinxTableRowColorEven}%
    \global\sphinxcolorlet{sphinxTableMergeColor}{\sphinxTableMergeColorEven}%
  \fi
}

% this will start the alternating colours, by letting \everycr increment
% the \rownum counter and reset the colours according to
% \sphinxSwitchCaseRowColor\rownum
\def\spx@table@@startbodycolorrows{%
    \noalign{%
       \global\CT@everycr{% Nota Bene: in a longtable with \hline the \everycr is
                          % done two extra times! but 2 is even, so this is ok
          \noalign{\global\advance\rownum\@ne % the xcolor \rowcolors base trick
% MEMO: colortbl \CT@row@color is expanded *after* the cell contents have been
% gathered and measured, so it can't be used to expose e.g. the colour to the
% cell contents macro code.  Of course if it is known how the colour is chosen
% the procedure could be done from inside the cell.  Simpler to set the colour
% in a public name sphinxTableRowColor at start of the row in this \noalign.
                   \sphinxSwitchCaseRowColor\rownum
                  }%
          \the\everycr
       }%
       \global\rownum\@ne % is done from inside table so ok with tabulary two passes
       \sphinxSwitchCaseRowColor\rownum % set up color for the first body row
       \sphinxrowcolorON  % turns on the colours for rows (this is superfluous
                          % as it now is also emitted by \sphinxtoprule for
                          % header rows)
    }% end of noalign contents
}

\def\sphinxrowcolorON{% the colours here must have been defined
  % this is the case if colorrows class from \sphinxtoprule expansion
       \gdef\CT@row@color{\ifspx@table@inmergedcell
                            \CT@color{sphinxTableMergeColor}%
                          \else
                            \CT@color{sphinxTableRowColor}%
                          \fi
                          \@tempdimb\dimexpr\col@sep+\sphinxcolorpanelextraoverhang\relax
                          \@tempdimc\@tempdimb
                         }%
}%
\def\sphinxrowcolorOFF{\global\let\CT@row@color\relax}%
\def\sphinxnorowcolor{\spx@table@hackCT@norowcolor}% inhibits row colour in one cell only
\def\spx@table@resetcolortbl{% can be executed from inside or outside a table
    \global\let\CT@row@color\relax
% we should probably be more cautious and not hard-code here the colortbl set-up
    \global\CT@everycr{\noalign{\global\let\CT@row@color\relax}\the\everycr}%
}

\def\spx@table@@toprulehook{%
        \noalign{%
          % Because of tabulary 2-pass system, if we don't want the colour
          % set-up at end of table to contaminate the headers at start of
          % table, we must reset explicitly the \everycr here.  But
          % we don't use the colortbl default value of \CT@everycr, as it
          % resets \CT@row@color to \relax but we want the next header rows
          % to obey same color scheme
          \global\CT@everycr{\the\everycr}%
% if we could require xcolor we could make it nice colour scheme with each new
% header row at 90% of previous row colour, for example.
          \global\sphinxcolorlet{sphinxTableRowColor}{sphinxTableRowColorHeader}%
          \global\sphinxcolorlet{sphinxTableMergeColor}{\sphinxTableMergeColorHeader}%
          \sphinxrowcolorON
         }%
}%

% this macro is needed in color tables as each \cline or \cmidrule (booktabs)
% consumes one \cr, offsetting the rownum parity.
\def\spx@table@@decrementrownum{\noalign{\global\advance\rownum\m@ne}}
\let\sphinxtabledecrementrownum\@empty

% At last the style macros

% \spx@toprule is what the styles define; the colorrows class will prepend
% some code in \sphinxtabletoprulehook
\def\sphinxtoprule{\spx@toprule\sphinxtabletoprulehook}

% standard style
\def\sphinxthistablewithstandardstyle{%
    % Those two are produced by the latex writer
    \def\sphinxhline      {\hline}%
    % \sphinxtabledecrementrownum is a no-op which is redefined by colorrows
    % to correct the \rownum increment induced by \cline in colorrows regime
    \def\sphinxcline      {\sphinxtabledecrementrownum\cline}%
    % Those three are inserted by the table templates
    \def\spx@toprule      {\hline}%
    \def\sphinxmidrule    {\hline}%
    \def\sphinxbottomrule {\hline}%
    % Merged cells width computation
    \def\sphinxarrayrulewidth{\arrayrulewidth}%
}

% booktabs style
% The \@xcmidrule patch below will do beyond its main stuff
%     \sphinxadjustcmidrulebelowsep
% Indeed the poor booktabs spacing with \cmidrule (if \sphinxbooktabscmidrule
% defined below is overwritten to use it) is quite awful.  Do
%     \let\sphinxadjustcmidrulebelowsep\empty
% if you prefer booktabs defaults.
\def\sphinxadjustcmidrulebelowsep{\belowrulesep=\aboverulesep}
\AtBeginDocument{% patch booktabs to avoid extra vertical space from
                 % consecutive \sphinxcline, if defined to use \cmidrule
  \ifdefined\@xcmidrule
    \let\spx@original@@xcmidrule\@xcmidrule
    \def\@xcmidrule{\sphinxadjustcmidrulebelowsep
                    % if we don't do that, two \sphinxcline in the same row
                    % will cause the second short rule to be shifted down
                    \ifx\@tempa\sphinxcline\let\@tempa\cmidrule\fi
                    \spx@original@@xcmidrule}%
  \fi
}
% wrappers to allow ultimate customization, e.g. via a container class, of the
% widths (aka thickness) associated with the booktabs rule (advanced users may
% even employ \specialrule here to control vertical spacing).
\def\sphinxbooktabstoprule   {\toprule}
\def\sphinxbooktabsmidrule   {\midrule}
\def\sphinxbooktabsbottomrule{\bottomrule}
\let\sphinxbooktabscmidrule  \@gobble % i.e. draw no short rules at all!
% You can redefine this to use \cmidrule with various options, such
% as \cmidrule(lr), but:
% Attention, if you want this to use \cmidrule (or \cline) you must
% also include the \sphinxtabledecrementrownum token like e.g. this
%     \def\sphinxbooktabscmidrule{\sphinxtabledecrementrownum\cmidrule}
% and it must be first due to internals of the \cmidrule usage of \futurelet,
% if the table uses row colours.

\def\sphinxthistablewithbooktabsstyle{%
    \let\sphinxhline\@empty % there is no wrapper macro here so if you want to change that
                            % you will have to redefine \sphinxthistablewithbooktabsstyle
    \def\sphinxcline     {\sphinxbooktabscmidrule}% defaults to \@gobble
    \def\spx@toprule     {\sphinxbooktabstoprule}%
    \def\sphinxmidrule   {\sphinxbooktabsmidrule}%
    \def\sphinxbottomrule{\sphinxbooktabsbottomrule}%
    \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth
                                  %  this would modify \z@ and break all of LaTeX...)
}
\AtBeginDocument{\@ifpackageloaded{booktabs}%
    {}%
    {\def\sphinxthistablewithbooktabsstyle{%
    \PackageWarning{sphinx}{%
Please add \string\usepackage{booktabs} to the preamble\MessageBreak
to allow local use of booktabs table style}%
    \textcolor{red}{\bfseries ADD LOADING OF booktabs TO THE 'preamble' KEY OF
                    latex\textunderscore elements}\par
    \sphinxthistablewithstandardstyle
    }}%
}%

% borderless style
\def\sphinxthistablewithborderlessstyle{%
    \let\sphinxhline      \@empty
    \let\sphinxcline      \@gobble
    \let\spx@toprule      \@empty
    \let\sphinxmidrule    \@empty
    \let\sphinxbottomrule \@empty
    \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth
                                  %  this would modify \z@ and break all of LaTeX...)
}%

% colorrows style
%
% this is defined to be executed only once (if both latex_book_style contains
% 'colorrows' and the table receives the class colorrows, this means the macro
% is executed twice, but it prepends hooks and one of them decrements \rownum so
% should be prepended only once).  The self-annihilation is done in a scope
% limiting environment.
\def\sphinxthistablewithcolorrowsstyle{%
% only do its job once
    \let\sphinxthistablewithcolorrowsstyle\@empty
%
    \let\spx@table@toprulehook         \spx@table@@toprulehook
    \let\spx@table@startbodycolorrows  \spx@table@@startbodycolorrows
    \let\sphinxtabledecrementrownum    \spx@table@@decrementrownum
    \spx@prepend\spx@table@toprulehook       \to\sphinxtabletoprulehook
    \spx@prepend\spx@table@startbodycolorrows\to\sphinxtableatstartofbodyhook
%
% this one is not set to \@empty by norowcolors, because it looks harmless
% to execute it always, as it simply resets to standard colortbl state after
% the table; so we don't need an @@ version for this one
    \spx@prepend\spx@table@resetcolortbl\to\sphinxtableafterendhook
}
\def\spx@prepend#1\to#2{% attention about using this only with #2 "storage macro"
    \toks@{#1}%
    \toks@\expandafter\expandafter\expandafter{\expandafter\the\expandafter\toks@#2}%
    \edef#2{\the\toks@}%
}%

\def\sphinxthistablewithnocolorrowsstyle{%
% rather than trying to remove the code added by 'rowcolors' style, we 
% simply make it no-op, without even checking if really it was activated.
    \let\spx@table@toprulehook       \@empty
    \let\spx@table@startbodycolorrows\@empty
    \let\sphinxtabledecrementrownum  \@empty
% we don't worry about \sphinxtableafterendhook as the \spx@table@resetcolortbl
% done at end can not do harm; and also we could have not bothered with the
% \sphinxtabledecrementrownum as its \rownum decrement, if active, is harmless
% in non-colorrows context
}

% The \sphinxarrayrulewidth is used for some complex matters of merged
% cells size computations
% tabularcolumns argument will override any global or local style
% regarding the presence or not of vertical separator.
\def\sphinxthistablewithvlinesstyle{%
    \def\sphinxarrayrulewidth{\arrayrulewidth}%
}%
\def\sphinxthistablewithnovlinesstyle{%
    \def\sphinxarrayrulewidth{\z@}% (attention! Do NOT assign to \sphinxarrayrulewidth
                                  %  this would modify \z@ and break all of LaTeX...)
}%
% (mixed style in the column specification can not be 100% well supported).

% default is the standard style
\def\sphinxthistablewithglobalstyle{\sphinxthistablewithstandardstyle}

\ifspx@opt@booktabs
    \RequirePackage{booktabs}
    \def\sphinxthistablewithglobalstyle{\sphinxthistablewithbooktabsstyle}
\fi
\ifspx@opt@borderless
    \def\sphinxthistablewithglobalstyle{\sphinxthistablewithborderlessstyle}
\fi
\ifspx@opt@colorrows % let the globalstyle trigger the colorrows style on top of it
    \expandafter\def\expandafter\sphinxthistablewithglobalstyle\expandafter
    {\sphinxthistablewithglobalstyle
     \sphinxthistablewithcolorrowsstyle
    }
\fi


\endinput