LaTeX: document what the style files provide and require

sphinx/texinputs/sphinx.sty

@@ -180,6 +180,37 @@
 \newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}
 
 
+%% MISCELLANEOUS CONTEXT
+%
+% flag to be set in a framed environment
+% (defined here as currently needed by three sphinxlatex....sty files and
+% even if not needed if such files are replaced, the definition does no harm)
+\newif\ifspx@inframed
+%
+% \spx@ifcaptionpackage (defined at begin document)
+%     is needed currently in macros from:
+%     sphinxlatexliterals.sty (sphinxVerbatim)
+%     sphinxlatextables.sty   (for some macros used in the table templates)
+%
+% \sphinxcaption is mark-up injected by the tabular and tabulary templates
+%     it is defined in sphinxlatextables.sty
+%
+% store the original \caption macro for usage with figures inside longtable
+% and tabulary cells. Make sure we get the final \caption in presence of
+% caption package, whether the latter was loaded before or after sphinx.
+\AtBeginDocument{%
+    \let\spx@originalcaption\caption
+    \@ifpackageloaded{caption}
+      {\let\spx@ifcaptionpackage\@firstoftwo
+       \caption@AtBeginDocument*{\let\spx@originalcaption\caption}%
+% in presence of caption package, drop our own \sphinxcaption whose aim was to
+% ensure same width of caption to all kinds of tables (tabular(y), longtable),
+% because caption package has its own width (or margin) option
+       \def\sphinxcaption{\caption}%
+      }%
+      {\let\spx@ifcaptionpackage\@secondoftwo}%
+}
+
 %% PASS OPTIONS
 %
 % pass options to hyperref; it must not have been loaded already
@@ -203,42 +234,35 @@
 %
 % as will be indicated below, secondary style files load some more packages
 %
-% for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
+% For \text macro (sphinx.util.texescape)
+% also for usage of \firstchoice@true(false) in sphinxlatexgraphics.sty
 \RequirePackage{amstext}
-% it was passed "warn" option from latex template
+% It was passed "warn" option from latex template in case it is already loaded
+% via some other package before \usepackage{sphinx} in preamble
 \RequirePackage{textcomp}
 % For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
 % for allowing figures in tables.
 \RequirePackage{float}
 % For floating figures in the text. Better to load after float.
 \RequirePackage{wrapfig}
-% control caption around literal-block
+% Provides \captionof, used once by latex writer (\captionof{figure})
 \RequirePackage{capt-of}
-\RequirePackage{needspace}
-% support hlist directive
+% Support hlist directive
 \RequirePackage{multicol}
 
 
 %% GRAPHICS
 %
+% It will always be needed, so let's load it here
 \RequirePackage{graphicx}
 \input{sphinxlatexgraphics.sty}
 
 
 %% FRAMED ENVIRONMENTS
-% For framing code-blocks and warning type notices, and shadowing topics
-\RequirePackage{framed}
 %
-% macros and environment for display literals (sphinxVerbatim, sphinxalltt)
-% and inline literals (\sphinxupquote); also defines \sphinxhref.
-% Requires: fancyvrb, alltt, upquote
-\input{sphinxlatexliterals.sty}
-%
-% topic and contents boxes: sphinxShadowBox uses framed.sty
-\input{sphinxlatexshadowbox.sty}
-%
-% notices and admonitions: sphinxheavybox uses again framed.sty
 \input{sphinxlatexadmonitions.sty}
+\input{sphinxlatexliterals.sty}
+\input{sphinxlatexshadowbox.sty}
 
 
 %% PYGMENTS
@@ -259,23 +283,16 @@
 
 %% TABLES
 %
-% Requires: tabulary, longtable, varwidth
-% extends tabulary and longtable via patches and custom macros to support
-% merged cells possibly containing code-blocks in complex tables
 \input{sphinxlatextables.sty}
 
 
 %% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
 %
-% Requires: remreset (old LaTeX only)
-% relates to numfig and numfig_secnum_depth configuration variables
 \input{sphinxlatexnumfig.sty}
 
 
 %% LISTS
 %
-% optionally extends LaTeX maximal list nesting depth and provides
-% \sphinxsetlistlabels macro used in mark-up
 \input{sphinxlatexlists.sty}
 
 
@@ -284,35 +301,25 @@
 % support large numbered footnotes in minipage; but this is now obsolete
 % from systematic use of savenotes environment around minipages
 \def\thempfootnote{\arabic{mpfootnote}}
-% this package provides savenotes environment (aka \savenotes/spewnotes)
-% For hyperlinked footnotes in tables; also for gathering footnotes from
-% topic and warning blocks. Also to allow code-blocks in footnotes.
-% Based on footnotehyper, extended to support tabulary multipass system
+% This package is needed to support hyperlinked footnotes in tables and
+% framed contents, and to allow code-blocks in footnotes.
 \RequirePackage{sphinxpackagefootnote}
 
 
 %% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
 %
-% requires makeidx
 \input{sphinxlatexindbibtoc.sty}
 
 
 %% STYLING
 %
-% page
-% requires parskip (legacy version) and, except if memoir class, fancyhdr
 \input{sphinxlatexstylepage.sty}
-% headings
-% requires titlesec and, if it is at 2.10.1, etoolbox to patch it
 \input{sphinxlatexstyleheadings.sty}
-% many \sphinx... prefixed commands to style text
 \input{sphinxlatexstyletext.sty}
 
 
 %% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
 %
-% this legacy code has remained very stable over the years
-% (fulllineitems was updated to support multiline signatures)
 \input{sphinxlatexobjects.sty}
 
 

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -3,6 +3,32 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexadmonitions.sty}[2021/01/27 admonitions]
 
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - sphinxadmonition (environment)
+%   This is a dispatch supporting
+%
+%   - note, hint, important, tip                 (via sphinxlightbox)
+%   - warning, caution, attention, danger, error (via sphinxheavybox)
+%
+%   Each sphinx<notice name> environment can be redefined by user.
+%   The defaults are customizable via various colour and dimension
+%   settings, cf sphinx docs (latex customization).
+%
+% Requires:
+\RequirePackage{framed}% used by sphinxheavybox
+%
+% Dependencies (they do not need to be defined at time of loading):
+% - of course the various colour and dimension options handled via sphinx.sty
+% - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
+% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
+
+% Provides: (also in sphinxlatexliterals.sty)
+\providecommand*\sphinxvspacefixafterfrenchlists{%
+   \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
+}
+
 % Some are quite plain
 % the spx@notice@bordercolor etc are set in the sphinxadmonition environment
 \newenvironment{sphinxlightbox}{%

sphinx/texinputs/sphinxlatexgraphics.sty

@@ -3,6 +3,30 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexgraphics.sty}[2021/01/27 graphics]
 
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - macros:
+%
+%   - \sphinxfigcaption
+%   - \sphinxincludegraphics
+%
+% - environments:
+%
+%   - sphinxfigure-in-table
+%
+% May change:
+%
+% - \sphinxcaption (at begin document)
+%
+% Also provides:
+%
+% - \sphinxsafeincludegraphics (default of \sphinxincludegraphics since 2.0)
+% - \spx@image@maxheight dimension (used by sphinxlatexadmonitions.sty)
+%
+% Requires:
+% \RequirePackage{graphicx}% done in sphinx.sty
+\RequirePackage{amstext}% needed for \firstchoice@true(false)
+
 % \sphinxincludegraphics resizes images larger than the TeX \linewidth (which
 % is adjusted in indented environments), or taller than a certain maximal
 % height (usually \textheight and this is reduced in the environments which use
@@ -85,21 +109,6 @@
   \sphinxsetvskipsforfigintablecaption
   \begin{minipage}{#1}%
 }{\end{minipage}}
-% store the original \caption macro for usage with figures inside longtable
-% and tabulary cells. Make sure we get the final \caption in presence of
-% caption package, whether the latter was loaded before or after sphinx.
-\AtBeginDocument{%
-    \let\spx@originalcaption\caption
-    \@ifpackageloaded{caption}
-      {\let\spx@ifcaptionpackage\@firstoftwo
-       \caption@AtBeginDocument*{\let\spx@originalcaption\caption}%
-% in presence of caption package, drop our own \sphinxcaption whose aim was to
-% ensure same width of caption to all kinds of tables (tabular(y), longtable),
-% because caption package has its own width (or margin) option
-       \def\sphinxcaption{\caption}%
-      }%
-      {\let\spx@ifcaptionpackage\@secondoftwo}%
-}
 % tabulary expands twice contents, we need to prevent double counter stepping
 \newcommand*\sphinxfigcaption
   {\ifx\equation$%$% this is trick to identify tabulary first pass

sphinx/texinputs/sphinxlatexindbibtoc.sty

@@ -3,6 +3,23 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexindbibtoc.sty}[2021/01/27 index, bib., toc]
 
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - environments: (backup defaults or get redefined)
+%
+%   - sphinxtheindex (direct mark-up or via python.ist or sphinx.xdy)
+%   - sphinxthebibliography
+%
+% - macros: (defines defaults)
+%
+%   - \sphinxmaketitle
+%   - \sphinxtableofcontents
+%   - \sphinxnonalphabeticalgroupname
+%   - \sphinxsymbolsname
+%   - \sphinxnumbersname
+%   - \sphinxcite
+%
+% Requires:
 \RequirePackage{makeidx}
 
 % fix the double index and bibliography on the table of contents

sphinx/texinputs/sphinxlatexlists.sty

@@ -3,6 +3,11 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexlists.sty}[2021/01/27 lists]
 
+% Provides support for this output mark-up from Sphinx latex writer:
+% - \sphinxsetlistlabels
+
+% Dependencies: the \spx@opt@maxlistdepth from sphinx.sty
+
 \newcommand\sphinxsetlistlabels[5]
 {% #1 = style, #2 = enum, #3 = enumnext, #4 = prefix, #5 = suffix
  % #2 and #3 are counters used by enumerate environement e.g. enumi, enumii.

sphinx/texinputs/sphinxlatexliterals.sty

@@ -3,16 +3,62 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexliterals.sty}[2021/01/27 code-blocks and parsed literals]
 
-% For highlighted code.
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - macros:
+%   - \sphinxLiteralBlockLabel
+%   - \sphinxSetupCaptionForVerbatim
+%   - \sphinxSetupCodeBlockInFootnote
+%   - \sphinxhref
+%   - \sphinxnolinkurl
+%   - \sphinxresetverbatimhllines
+%   - \sphinxunactivateextrasandspace
+%   - \sphinxupquote
+%   - \sphinxurl
+%
+% - environments:
+%   - sphinxVerbatim
+%   - sphinxVerbatimintable
+%   - sphinxalltt
+%
+% Dependency:
+%
+% - hyperref (for \phantomsection and \capstart) (loaded later)
+%
+% Executes \RequirePackage for:
+%
+% - framed
+% - fancyvrb
+% - alltt
+% - upquote
+% - needspace
+
+% also in sphinxlatexadmonitions.sty:
+% This is a workaround to a "feature" of French lists, when literal block
+% follows immediately; usable generally (does only \par then), a priori...
+\providecommand*\sphinxvspacefixafterfrenchlists{%
+   \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
+}
+
+% For framing allowing pagebreaks
+\RequirePackage{framed}
+% For source code
+% MEMO: fancyvrb is used mainly to
+% 1- control horizontal and vertical spacing
+% 2- optional line numbering
+% 3- optional line emphasizing
+% 4- while still allowing expansion of Pygments latex mark-up
+% Other aspects such as framing, caption handling, codeline wrapping are
+% added on top of it. We should stop using fancyvrb and implement
+% 1, 2, 3, 4 by own Sphinx fully native Verbatim. This would allow to solve
+% limitations with wrapped long code line not allowing page break.
 \RequirePackage{fancyvrb}
-\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
-% sphinxVerbatim must be usable by third party without requiring hllines set-up
-\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}}
-\sphinxresetverbatimhllines
 % For parsed-literal blocks.
 \RequirePackage{alltt}
 % Display "real" single quotes in literal blocks.
 \RequirePackage{upquote}
+% Skip to next page if not enough space at bottom
+\RequirePackage{needspace}
 
 % Based on use of "fancyvrb.sty"'s Verbatim.
 % - with framing allowing page breaks ("framed.sty")
@@ -20,6 +66,12 @@
 % - with possibly of a top caption, non-separable by pagebreak.
 % - and usable inside tables or footnotes ("sphinxpackagefootnote.sty").
 
+% for emphasizing lines
+\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
+% sphinxVerbatim must be usable by third party without requiring hllines set-up
+\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}}
+\sphinxresetverbatimhllines
+
 % Prior to Sphinx 1.5, \Verbatim and \endVerbatim were modified by Sphinx.
 % The aliases defined here are used in sphinxVerbatim environment and can
 % serve as hook-points with no need to modify \Verbatim itself.
@@ -36,7 +88,6 @@
 % analogous to \listoffigures, but for the code listings (foo = chosen title.)
 \newcommand*{\ext@literalblock}{lol}
 
-\newif\ifspx@inframed % flag set if we are already in a framed environment
 % if forced use of minipage encapsulation is needed (e.g. table cells)
 \newif\ifsphinxverbatimwithminipage   \sphinxverbatimwithminipagefalse
 
@@ -181,11 +232,6 @@
 % This box to measure contents if nested as inner \MakeFramed requires then
 % minipage encapsulation but too long contents then break outer \MakeFramed
 \newbox\sphinxVerbatim@ContentsBox
-% This is a workaround to a "feature" of French lists, when literal block
-% follows immediately; usable generally (does only \par then), a priori...
-\newcommand*\sphinxvspacefixafterfrenchlists{%
-   \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
-}
 % Holder macro for labels of literal blocks. Set-up by LaTeX writer.
 \newcommand*\sphinxLiteralBlockLabel {}
 \newcommand*\sphinxSetupCaptionForVerbatim [1]

sphinx/texinputs/sphinxlatexnumfig.sty

@@ -3,6 +3,9 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexnumfig.sty}[2021/01/27 numbering]
 
+% Requires: remreset (old LaTeX only)
+% relates to numfig and numfig_secnum_depth configuration variables
+
 % LaTeX 2018-04-01 and later provides \@removefromreset
 \ltx@ifundefined{@removefromreset}
     {\RequirePackage{remreset}}

sphinx/texinputs/sphinxlatexobjects.sty

@@ -3,7 +3,20 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexobjects.sty}[2021/01/27 documentation environments]
 
-%  (some macros here used by \maketitle in sphinxmanual.cls and sphinxhowto.cls)
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - environments
+%
+%   - fulllineitems
+%   - productionlist
+%   - optionlist
+%   - DUlineblock (also "lineblock")
+%
+% - macros
+%
+%   - \DUrole
+%   - various legacy support macros related to author and release
+%     data of documented objects and modules.
 
 % \moduleauthor{name}{email}
 \newcommand{\moduleauthor}[2]{}

sphinx/texinputs/sphinxlatexshadowbox.sty

@@ -3,6 +3,20 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexshadowbox.sty}[2021/01/27 sphinxShadowBox]
 
+% Provides support for this output mark-up from Sphinx latex writer:
+%
+% - sphinxShadowBox (environment)
+%
+% Dependencies (they do not need to be defined at time of loading):
+%
+% - of course the various colour and dimension options handled via sphinx.sty
+% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote
+% - \ifspx@inframed defined in sphinx.sty
+%
+% Requires:
+\RequirePackage{framed}
+
 % Again based on use of "framed.sty", this allows breakable framed boxes.
 \long\def\spx@ShadowFBox#1{%
   \leavevmode\begingroup

sphinx/texinputs/sphinxlatexstyleheadings.sty

@@ -28,6 +28,23 @@
    \fi
   }%
  }{}
+
+% Augment the sectioning commands used to get our own font family in place,
+% and reset some internal data items (\titleformat from titlesec package)
+\titleformat{\section}{\Large\py@HeaderFamily}%
+            {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}
+\titleformat{\subsection}{\large\py@HeaderFamily}%
+            {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}
+\titleformat{\subsubsection}{\py@HeaderFamily}%
+            {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}
+% By default paragraphs (and subsubsections) will not be numbered because
+% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
+\titleformat{\paragraph}{\py@HeaderFamily}%
+            {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}
+\titleformat{\subparagraph}{\py@HeaderFamily}%
+            {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}
+
+
 % Since Sphinx 1.5, users should use HeaderFamily key to 'sphinxsetup' rather
 % than defining their own \py@HeaderFamily command (which is still possible).
 % Memo: \py@HeaderFamily is also used by \maketitle as defined in
@@ -57,19 +74,10 @@
     }}
 }{}% <-- "false" clause of \@ifpackagewith
 
-% Augment the sectioning commands used to get our own font family in place,
-% and reset some internal data items (\titleformat from titlesec package)
-\titleformat{\section}{\Large\py@HeaderFamily}%
-            {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}
-\titleformat{\subsection}{\large\py@HeaderFamily}%
-            {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}
-\titleformat{\subsubsection}{\py@HeaderFamily}%
-            {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}
-% By default paragraphs (and subsubsections) will not be numbered because
-% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
-\titleformat{\paragraph}{\py@HeaderFamily}%
-            {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}
-\titleformat{\subparagraph}{\py@HeaderFamily}%
-            {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}
+% fix fncychap's bug which uses prematurely the \textwidth value
+\@ifpackagewith{fncychap}{Bjornstrup}
+ {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
+ {}% <-- "false" clause of \@ifpackagewith
+
 
 \endinput

sphinx/texinputs/sphinxlatexstylepage.sty

@@ -17,6 +17,7 @@
 \sloppy
 \hbadness = 5000                % don't print trivial gripes
 
+% Require package fancyhdr except under memoir class
 \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
 % Use \pagestyle{normal} as the primary pagestyle for text.
 % Redefine the 'normal' header/footer style when using "fancyhdr" package:
@@ -74,9 +75,5 @@
    % Users of memoir class are invited to redefine 'normal' style in preamble
   }
 
-% fix fncychap's bug which uses prematurely the \textwidth value
-\@ifpackagewith{fncychap}{Bjornstrup}
- {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
- {}% <-- "false" clause of \@ifpackagewith
 
 \endinput

sphinx/texinputs/sphinxlatexstyletext.sty

@@ -3,6 +3,9 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatexstyletext.sty}[2021/01/27 text styling]
 
+% Basically everything here consists of macros which are part of the latex
+% markup produced by the Sphinx latex writer
+
 % Some custom font markup commands.
 \protected\def\sphinxstrong#1{\textbf{#1}}
 \protected\def\sphinxcode#1{\texttt{#1}}

sphinx/texinputs/sphinxlatextables.sty

@@ -3,9 +3,37 @@
 % change this info string if making any custom modification
 \ProvidesFile{sphinxlatextables.sty}[2021/01/27 tables]%
 
-% IMPORTANT: all this is to be kept in sync with the templates
-% longtable.tex_t, tabular.tex_t, tabulary.tex_t and the actual
-% Sphinx latex writer output.
+% 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
+%
+% Executes \RequirePackage for:
+%
+% - tabulary
+% - longtable
+% - varwidth
+%
+% 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

sphinx/texinputs/sphinxpackagefootnote.sty

@@ -1,6 +1,11 @@
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{sphinxpackagefootnote}%
  [2021/01/26 v1.1b footnotehyper adapted to sphinx (Sphinx team)]
+% Provides support for this output mark-up from Sphinx latex writer:
+% - footnote environment
+% - savenotes environment (table templates)
+% - \sphinxfootnotemark
+%
 %%
 %% Package: sphinxpackagefootnote
 %% Version: based on footnotehyper.sty 2021/01/26 v1.1b