`'sphinxpackageoptions'` for key=value styling of Sphinx LaTeX

doc/config.rst

@@ -1694,9 +1694,15 @@ These options influence LaTeX output. See further :doc:`latex`.
         example ``100px=1in``, one can use ``'0.01in'`` but it is more precise
         to use ``'47363sp'``. To obtain ``72px=1in``, use ``'1bp'``.
 
+        .. versionadded:: 1.5
+     ``'sphinxpackageoptions'``
+        A comma separated list of ``key=value`` package options for the Sphinx
+        LaTeX style, default empty. See :doc:`latex`.
+
         .. versionadded:: 1.5
      ``'passoptionstopackages'``
-        "PassOptionsToPackage" call, default empty.
+        A string which will be positioned early in the preamble, designed to
+        contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
 
         .. versionadded:: 1.4
      ``'geometry'``

doc/latex.rst

@@ -41,27 +41,197 @@ preamble of relevant ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
 or ``\definecolor`` commands. The ``'preamble'`` key of
 :confval:`latex_elements` will serve for inserting these commands. If they are
 numerous, it may prove more convenient to assemble them into a specialized
-file :file:`mycustomizedmacros.tex` and then use::
+file :file:`mystyle.tex` and then use::
 
-    'preamble': '\\makeatletter\\input{mycustomizedmacros.tex}\\makeatother',
+    'preamble': '\\makeatletter\\input{mystyle.tex}\\makeatother',
 
-More advanced LaTeX users will set up a style file
+or, better, to set up a style file
-:file:`mycustomizedmacros.sty`, which can then be loaded via::
+:file:`mystyle.sty` which can then be loaded via::
 
-    'preamble': '\\usepackage{mycustomizedmacros}',
+    'preamble': '\\usepackage{mystyle}',
 
 The :ref:`build configuration file <build-config>` file for the project needs
 to have its variable :confval:`latex_additional_files` appropriately
 configured, for example::
 
-    latex_additional_files = ["mycustomizedmacros.sty"]
+    latex_additional_files = ["mystyle.sty"]
 
 Such *LaTeX Sphinx theme* files could possibly be contributed in the
 future by advanced users for wider use.
 
-Let us list here some examples of macros, lengths, colors, which are inherited
+The ``'sphinxpackageoptions'`` key to :confval:`latex_elements` provides a
-from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
+more convenient interface to various style parameters. It is a comma separated
-:file:`sphinxmanual.cls`, and can be customized.
+string of ``key=value`` instructions::
+
+    key1=value1,key2=value2, ...
+
+which will be passed as the optional parameter to the Sphinx LaTeX style \file::
+
+    \usepackage[<sphinxpackageoptions>]{sphinx}
+
+It is possible to modify later the options (even midway in the
+document using a ``.. raw:: latex`` directive) via use of the command
+``\sphinxsetup{<options>}``, with the same option ``key=value`` syntax.
+
+.. versionadded:: 1.5
+
+Here is the current list:
+
+``verbatimwithframe``
+    default ``true``. Boolean to use or not frames around
+    :rst:dir:`code-block`\ s and literal includes. Setting it to ``false``
+    does not deactivate use of package "framed", because it is still in use
+    for the optional background colour (see below).
+
+    .. attention::
+
+       LaTeX wants *lowercase* ``=true`` or  ``=false`` here.
+
+``verbatimwrapslines``
+    default ``true``. Tells whether long lines in :rst:dir:`code-block`\ s
+    should be wrapped. It is theoretically possible to customize this even
+    more and decide at which characters a line-break can occur and whether
+    before or after, but this is accessible currently only by re-defining some
+    macros with complicated LaTeX syntax from :file:`sphinx.sty`.
+
+``TitleColor``
+    default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
+    via use of package "titlesec".) It must obey the syntax of the
+    ``\definecolor`` command. Check the documentation of packages ``color`` or
+    ``xcolor``.
+
+``InnerLinkColor``
+    default ``{rgb}{0.208,0.374,0.486}``. A colour passed to ``hyperref`` as
+    value of ``linkcolor``  and ``citecolor``.
+
+``OuterLinkColor``
+    default ``{rgb}{0.216,0.439,0.388}``. A colour passed to ``hyperref`` as
+    value of ``filecolor``, ``menucolor``, and ``urlcolor``.
+
+``VerbatimColor``
+    default ``{rgb}{1,1,1}``. The background colour for
+    :rst:dir:`code-block`\ s. The default is white.
+
+``VerbatimBorderColor``
+    default ``{rgb}{0,0,0}``. The frame color, defaults to black.
+
+``verbatimsep``
+    default ``\fboxsep``. The separation between code lines and the frame.
+
+``verbatimborder``
+    default ``\fboxrule``. The width of the frame around
+    :rst:dir:`code-block`\ s.
+
+``shadowsep``
+    default ``5pt``. The separation between contents and frame for
+    :dudir:`contents` and :dudir:`topic` boxes.
+
+``shadowsize``
+    default ``4pt``. The width of the lateral "shadow" to the right.
+
+``shadowrule``
+    default ``\fboxrule``. The width of the frame around :dudir:`topic` boxes.
+
+``notebordercolor``
+    default ``{rgb}{0,0,0}``. The colour for the two horizontal rules used by
+    Sphinx in LaTeX for styling a
+    :dudir:`note` admonition. Defaults to black.
+
+``hintbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``importantbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``tipbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``noteborder``
+    default ``0.5pt``. The width of the two horizontal rules.
+
+``hintborder``
+    default ``0.5pt``. id.
+
+``importantborder``
+    default ``0.5pt``. id.
+
+``tipborder``
+    default ``0.5pt``. id.
+
+``warningbordercolor``
+    default ``{rgb}{0,0,0}``. The colour of the frame for :dudir:`warning` type
+    admonitions. Defaults to black.
+
+``cautionbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``attentionbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``dangerbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``errorbordercolor``
+    default ``{rgb}{0,0,0}``. id.
+
+``warningbgcolor``
+    default ``{rgb}{1,1,1}``. The background colour for :dudir:`warning` type
+    admonition, defaults to white.
+
+``cautionbgcolor``
+    default ``{rgb}{1,1,1}``. id.
+
+``attentionbgcolor``
+    default ``{rgb}{1,1,1}``. id.
+
+``dangerbgcolor``
+    default ``{rgb}{1,1,1}``. id.
+
+``errorbgcolor``
+    default ``{rgb}{1,1,1}``. id.
+
+``warningborder``
+    default ``1pt``. The width of the frame.
+
+``cautionborder``
+    default ``1pt``. id.
+
+``attentionborder``
+    default ``1pt``. id.
+
+``dangerborder``
+    default ``1pt``. id.
+
+``errorborder``
+    default ``1pt``. id.
+
+``AtStartFootnote``
+    default ``\\mbox{ }``. LaTeX macros inserted at the start of the footnote
+    text at bottom of page, after the footnote number.
+
+``BeforeFootnote``
+    default ``\\leavevmode\\unskip``. LaTeX macros inserted before the footnote
+    mark. The default removes possible space before it.
+
+    It can be set to empty (``BeforeFootnote={},``) to recover the earlier
+    behaviour of Sphinx, or alternatively contain a ``\\nobreak\\space`` or a
+    ``\\thinspace`` after the ``\\unskip`` to insert some chosen
+    (non-breakable) space.
+
+    .. versionadded:: 1.5
+       formerly, footnotes from explicit mark-up were
+       preceded by a space (hence a linebreak there was possible), but
+       automatically generated footnotes had no such space.
+
+``HeaderFamily``
+    default ``\\sffamily\\bfseries``. Sets the font used by headings.
+
+In the future, possibly more keys will be made available. As seen above, they
+may even be used for LaTeX commands.
+
+Let us now list some macros from the package file
+:file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
+:file:`sphinxmanual.cls`, which can be entirely redefined, if desired.
 
 - text styling commands (they have one argument): ``\sphinx<foo>`` with
   ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
@@ -84,38 +254,22 @@ from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
 
   .. versionadded:: 1.5
      the new macros are wrappers of the formerly hard-coded ``\texttt``,
-     ``\emph``, ... The default definitions can be found near the end of
+     ``\emph``, ... The default definitions can be found in
      :file:`sphinx.sty`.
-- parameters for paragraph level environments: with ``<foo>`` one of
+- paragraph level environments: for each admonition type ``<foo>``, the
-  :dudir:`warning`, :dudir:`caution`, :dudir:`attention`,
-  :dudir:`danger`, :dudir:`error`, the colours
-  *sphinx<foo>bordercolor* and *sphinx<foo>bgcolor* can be
-  re-defined using ``\definecolor`` command. The
-  ``\sphinx<foo>border`` is a command (not a LaTeX length) which
-  specifies the thickness of the frame (default ``1pt``) and can be
-  ``\renewcommand`` 'd. The same applies with ``<foo>`` one of
-  :dudir:`note`, :dudir:`hint`, :dudir:`important`, :dudir:`tip`, but
-  the background colour is not implemented by the default environments
-  and the top and bottom rule thickness default is ``0.5pt``.
-
-  .. versionchanged:: 1.5
-     customizability of the parameters for each type of admonition.
-- paragraph level environments: for each admonition as in the previous item, the
   used environment is named ``sphinx<foo>``. They may be ``\renewenvironment``
   'd individually, and must then be defined with one argument (it is the heading
   of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
   English is the document language). Their default definitions use either the
   *sphinxheavybox* (for the first listed directives) or the *sphinxlightbox*
   environments, configured to use the parameters (colours, border thickness)
-  specific to each type, as mentioned in the previous item.
+  specific to each type, which can be set via ``'sphinxpackageoptions'`` string.
 
   .. versionchanged:: 1.5
      use of public environment names, separate customizability of the parameters.
 - the :dudir:`contents` directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
-  Its default definition obeys three LaTeX lengths (not commands) as parameters:
+  See above for the three dimensions associated with it.
-  ``\sphinxshadowsep`` (distance from contents), ``\sphinxshadowsize`` (width of
-  lateral shadow), ``\sphinxshadowrule`` (thickness of the frame).
 
   .. versionchanged:: 1.5
      use of public names for the three lengths. The environment itself was
@@ -124,8 +278,7 @@ from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
   implemented using ``sphinxVerbatim`` environment which is a wrapper of
   ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
   of the top caption and the wrapping of long lines, and a frame which allows
-  pagebreaks. The LaTeX lengths (not commands) ``\sphinxverbatimsep`` and
+  pagebreaks. Inside tables the used
-  ``\sphinxverbatimborder`` customize the framing. Inside tables the used
   environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
   allows a caption).
 
@@ -134,9 +287,10 @@ from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
      which is the one of ``OriginalVerbatim`` too), and custom one is called
      ``sphinxVerbatim``. Also, earlier version of Sphinx used
      ``OriginalVerbatim`` inside tables (captions were lost, long code lines
-     were not wrapped), they now use ``sphinxVerbatimintable``.
+     were not wrapped), it now uses there ``sphinxVerbatimintable``.
   .. versionadded:: 1.5
-     the two customizable lengths, the ``sphinxVerbatimintable``.
+     the two customizable lengths, the ``sphinxVerbatimintable``, the boolean
+     toggles described above.
 - by default the Sphinx style file ``sphinx.sty`` includes the command
   ``\fvset{fontsize=\small}`` as part of its configuration of
   ``fancyvrb.sty``. The user may override this for example via
@@ -145,30 +299,6 @@ from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
 
   .. versionadded:: 1.5
      formerly, the use of ``\small`` for code listings was not customizable.
-- miscellaneous colours: *InnerLinkColor*, *OuterLinkColor* (used in
-  ``hyperref`` options), *TitleColor* (used for titles via  ``titlesec``),
-  *VerbatimColor* (background colour) and *VerbatimBorderColor* (used for
-  displaying source code examples).
-- the ``\sphinxAtStartFootnote`` is inserted between footnote numbers and their
-  texts, by default it does ``\mbox{ }``.
-- the ``\sphinxBeforeFootnote`` command is executed before each footnote, its
-  default definition is::
-
-    \newcommand*{\sphinxBeforeFootnote}{\leavevmode\unskip}
-
-  You can ``\renewcommand`` it to do nothing in order to recover the earlier
-  behaviour of Sphinx, or alternatively add a ``\nobreak\space`` or a
-  ``\thinspace`` after the ``\unskip`` in the definition to insert some
-  (non-breakable) space.
-
-  .. versionadded:: 1.5
-     formerly, footnotes from explicit mark-up were preceded by a space
-     allowing a linebreak, but automatically generated footnotes had no such
-     space.
-- use ``\sphinxSetHeaderFamily`` to set the font used by headings
-  (default is ``\sffamily\bfseries``).
-
-  .. versionadded:: 1.5
 - the section, subsection, ...  headings are set using  *titlesec*'s
   ``\titleformat`` command. Check :file:`sphinx.sty` for the definitions.
 - for the ``'sphinxmanual'`` class (corresponding to the fifth element of

sphinx/templates/latex/content.tex_t

@@ -1,6 +1,5 @@
 %% Generated by Sphinx.
 \def\sphinxdocclass{<%= docclass %>}
-<%= passoptionstosphinx %>
 \documentclass[<%= papersize %>,<%= pointsize %><%= classoptions %>]{<%= wrapperclass %>}
 \ifdefined\pdfpxdimen
    \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
@@ -16,7 +15,7 @@
 <%= fontpkg %>
 <%= fncychap %>
 <%= longtable %>
-\usepackage{sphinx}
+\usepackage[<%= sphinxpackageoptions %>]{sphinx}
 \usepackage{multirow}
 \usepackage{eqparbox}
 <%= usepackages %>

sphinx/texinputs/footnotehyper-sphinx.sty

@@ -1,6 +1,6 @@
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{footnotehyper-sphinx}%
- [2016/10/16 v0.9f hyperref aware footnote.sty for sphinx (JFB)]
+ [2016/10/27 v0.9f hyperref aware footnote.sty for sphinx (JFB)]
 %%
 %% Package: footnotehyper-sphinx
 %% Version: based on footnotehyper.sty v0.9f (2016/10/03)
@@ -12,17 +12,7 @@
 %% 2. no need to check if footnote.sty was loaded,
 %% 3. a special tabulary compatibility layer added, (partial but enough for
 %% Sphinx),
-%% 4. the \sphinxfootnotemark command is added. Its rôle is to silently remove
+%% 4. \sphinxfootnotemark, and use of \spx@opt@BeforeFootnote from sphinx.sty.
-%% footnote marks from locations like the tables of contents, or page headers,
-%% and to be compatible with hyperref constructions of bookmarks, and survive
-%% to \MakeUppercase command or such which may be used to typeset chapter
-%% titles for example.
-%% 5. the \sphinxBeforeFootnote is added: reST syntax implies that a space token
-%% is needed before footnote mark-up like [#]_ and it goes to latex file (and
-%% a line break can happen before the footnote mark), but for generated
-%% footnotes from latex_show_urls = 'footnote' there is no such space. The
-%% hook normalizes this, and by default uses no space.
-%%
 %% Note: with \footnotemark[N]/\footnotetext[N] syntax, hyperref
 %% does not insert an hyperlink. This is _not_ improved here.
 %%
@@ -99,8 +89,8 @@
     \if@savingnotes\expandafter\fn@fntext\else\expandafter\H@@footnotetext\fi
     {\unvbox\z@}\endgroup
 }%
-%% \sphinxBeforeFootnote added 2016/10/16
+%% \spx@opt@BeforeFootnote is defined in sphinx.sty
-\def\FNH@fixed@footnote {\sphinxBeforeFootnote\ifx\@currenvir\fn@footnote
+\def\FNH@fixed@footnote {\spx@opt@BeforeFootnote\ifx\@currenvir\fn@footnote
     \expandafter\FNH@footnoteenv\else\expandafter\fn@latex@@footnote\fi }%
 \def\FNH@footnoteenv {\@ifnextchar[\FNH@xfootnoteenv%]
     {\stepcounter\@mpfn
@@ -154,15 +144,13 @@
     \typeout{\meaning\@makefntext}%
     \let\fn@prefntext\@empty\let\fn@postfntext\@empty
 }%
-%% \sphinxfootnotemark: usable in section titles and silently removed from TOCs
+%% \sphinxfootnotemark: usable in section titles and silently removed from
+%% TOCs.
 \def\sphinxfootnotemark [#1]%
-   {\ifx\thepage\relax\else \protect\sphinxBeforeFootnote
+   {\ifx\thepage\relax\else \protect\spx@opt@BeforeFootnote
                             \protect\footnotemark[#1]\fi}%
-\AtBeginDocument
+\AtBeginDocument % let hyperref less complain
    {\pdfstringdefDisableCommands{\def\sphinxfootnotemark [#1]{}}}%
-%% before 1.5, Sphinx left a (breakable) space before user generated footnotes
-%% but no space before automatically generated footnotes.
-\def\sphinxBeforeFootnote {\leavevmode\unskip}%
 \endinput
 %%
 %% End of file `footnotehyper-sphinx.sty'.

sphinx/texinputs/sphinx.sty

@@ -6,15 +6,122 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2016/10/26 v1.5 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2016/10/27 v1.5 LaTeX package (Sphinx markup)]
 
 % Handle package options via "kvoptions" (later loaded by hyperref anyhow)
 \RequirePackage{kvoptions}
 \SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
+
 \DeclareBoolOption{dontkeepoldnames} % \ifspx@opt@dontkeepoldnames = \iffalse
 \DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
+
+% colour values must be given in format accepted by color's \definecolor
+\DeclareStringOption[{rgb}{0.126,0.263,0.361}]{TitleColor}
+% for hyperref
+\DeclareStringOption[{rgb}{0.208,0.374,0.486}]{InnerLinkColor}
+\DeclareStringOption[{rgb}{0.216,0.439,0.388}]{OuterLinkColor}
+% code-blocks and literal includes
+\DeclareStringOption[{rgb}{1,1,1}]{VerbatimColor}
+\DeclareStringOption[{rgb}{0,0,0}]{VerbatimBorderColor}
+\DeclareStringOption[\fboxsep]{verbatimsep}
+\DeclareStringOption[\fboxrule]{verbatimborder}
+\DeclareBoolOption[true]{verbatimwithframe}
+\DeclareBoolOption[true]{verbatimwrapslines}
+% topic boxes
+\DeclareStringOption[5pt]{shadowsep}
+\DeclareStringOption[4pt]{shadowsize}
+\DeclareStringOption[\fboxrule]{shadowrule}
+% admonition boxes, "light" style
+\DeclareStringOption[{rgb}{0,0,0}]{notebordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{hintbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{importantbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{tipbordercolor}
+\DeclareStringOption[0.5pt]{noteborder}
+\DeclareStringOption[0.5pt]{hintborder}
+\DeclareStringOption[0.5pt]{importantborder}
+\DeclareStringOption[0.5pt]{tipborder}
+% admonition boxes, "heavy" style
+\DeclareStringOption[{rgb}{0,0,0}]{warningbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{cautionbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{attentionbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{dangerbordercolor}
+\DeclareStringOption[{rgb}{0,0,0}]{errorbordercolor}
+\DeclareStringOption[{rgb}{1,1,1}]{warningbgcolor}
+\DeclareStringOption[{rgb}{1,1,1}]{cautionbgcolor}
+\DeclareStringOption[{rgb}{1,1,1}]{attentionbgcolor}
+\DeclareStringOption[{rgb}{1,1,1}]{dangerbgcolor}
+\DeclareStringOption[{rgb}{1,1,1}]{errorbgcolor}
+\DeclareStringOption[1pt]{warningborder}
+\DeclareStringOption[1pt]{cautionborder}
+\DeclareStringOption[1pt]{attentionborder}
+\DeclareStringOption[1pt]{dangerborder}
+\DeclareStringOption[1pt]{errorborder}
+
+% Footnotes
+\DeclareStringOption[\mbox{ }]{AtStartFootnote}
+% we need a public macro name for direct use in latex file
+\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote}
+% no such need for this one, used inside other macros
+\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote}
+
+% some font styling.
+\DeclareStringOption[\sffamily\bfseries]{HeaderFamily}
 \DeclareDefaultOption{\@unknownoptionerror}
 \ProcessKeyvalOptions*
+% don't allow use of maxlistdepth via \sphinxsetup.
+\DisableKeyvalOption{sphinx}{maxlistdepth}
+
+% We declare the \dimen registers here. Those are customizable via options.
+\newdimen\sphinxverbatimsep
+\newdimen\sphinxverbatimborder
+\newdimen\sphinxshadowsep
+\newdimen\sphinxshadowsize
+\newdimen\sphinxshadowrule
+% This one is dynamical, don't set it.
+\newdimen\spx@notice@border
+% Other dimensions are customizable by options and declare macros.
+
+\newcommand*\sphinx@setup
+{%
+ \sphinxverbatimsep   \dimexpr\spx@opt@verbatimsep   \relax
+ \sphinxverbatimborder\dimexpr\spx@opt@verbatimborder\relax
+ \sphinxshadowsep     \dimexpr\spx@opt@shadowsep     \relax
+ \sphinxshadowsize    \dimexpr\spx@opt@shadowsize    \relax
+ \sphinxshadowrule    \dimexpr\spx@opt@shadowrule    \relax
+ % they will be embedded in \dimexpr ... \relax at time of use
+ \let\sphinxnoteborder     \spx@opt@noteborder
+ \let\sphinxhintborder     \spx@opt@hintborder
+ \let\sphinximportantborder\spx@opt@importantborder
+ \let\sphinxtipborder      \spx@opt@tipborder
+ \let\sphinxwarningborder  \spx@opt@warningborder
+ \let\sphinxcautionborder  \spx@opt@cautionborder
+ \let\sphinxattentionborder\spx@opt@attentionborder
+ \let\sphinxdangerborder   \spx@opt@dangerborder
+ \let\sphinxerrorborder    \spx@opt@errorborder
+ % first execution of \sphinx@setup will be after having loaded color/xcolor
+ \def\@tempa ##1##2##3{\edef\@tempb{\noexpand##1{##2}##3}\@tempb}%
+ \@tempa\definecolor{TitleColor}                \spx@opt@TitleColor
+ \@tempa\definecolor{InnerLinkColor}            \spx@opt@InnerLinkColor
+ \@tempa\definecolor{OuterLinkColor}            \spx@opt@OuterLinkColor
+ \@tempa\definecolor{VerbatimColor}             \spx@opt@VerbatimColor
+ \@tempa\definecolor{VerbatimBorderColor}       \spx@opt@VerbatimBorderColor
+ \@tempa\definecolor{sphinxnotebordercolor}     \spx@opt@notebordercolor
+ \@tempa\definecolor{sphinxhintbordercolor}     \spx@opt@hintbordercolor
+ \@tempa\definecolor{sphinximportantbordercolor}\spx@opt@importantbordercolor
+ \@tempa\definecolor{sphinxtipbordercolor}      \spx@opt@tipbordercolor
+ \@tempa\definecolor{sphinxwarningbordercolor}  \spx@opt@warningbordercolor
+ \@tempa\definecolor{sphinxcautionbordercolor}  \spx@opt@cautionbordercolor
+ \@tempa\definecolor{sphinxattentionbordercolor}\spx@opt@attentionbordercolor
+ \@tempa\definecolor{sphinxdangerbordercolor}   \spx@opt@dangerbordercolor
+ \@tempa\definecolor{sphinxerrorbordercolor}    \spx@opt@errorbordercolor
+ \@tempa\definecolor{sphinxwarningbgcolor}      \spx@opt@warningbgcolor
+ \@tempa\definecolor{sphinxcautionbgcolor}      \spx@opt@cautionbgcolor
+ \@tempa\definecolor{sphinxattentionbgcolor}    \spx@opt@attentionbgcolor
+ \@tempa\definecolor{sphinxdangerbgcolor}       \spx@opt@dangerbgcolor
+ \@tempa\definecolor{sphinxerrorbgcolor}        \spx@opt@errorbgcolor
+}
+% additional user interface: options can be changed midway in a document!
+\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}\sphinx@setup}
 
 % this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by
 % hyperref.sty, but we need it before, and the first release of
@@ -72,14 +179,8 @@
 % Display "real" single quotes in literal blocks.
 \RequirePackage{upquote}
 
-% Redefine these colors to your liking in the preamble.
+% Initialize style parameters
-\definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
+\sphinx@setup
-\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
-\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
-% Redefine these colors to something if you want to have colored
-% background and border for code examples.
-\definecolor{VerbatimColor}{rgb}{1,1,1}
-\definecolor{VerbatimBorderColor}{rgb}{0,0,0}
 
 % FIXME: the reasons might be obsolete (better color drivers now?)
 % use pdfoutput for pTeX and dvipdfmx
@@ -117,8 +218,7 @@
 \pagestyle{empty}               % start this way
 
 % Use this to set the font family for headers and other decor:
-\newcommand{\py@HeaderFamily}{\sffamily\bfseries}
+\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily}
-\newcommand{\sphinxSetHeaderFamily}[1]{\renewcommand{\py@HeaderFamily}{#1}}
 
 % Redefine the 'normal' header/footer style when using "fancyhdr" package:
 \spx@ifundefined{fancyhf}{}{
@@ -147,7 +247,7 @@
 }
 
 % Some custom font markup commands.
-% *** the macros without \sphinx prefix are still defined at bottom of file ***
+% *** the macros without \sphinx prefix are still defined near end of file ***
 \newcommand{\sphinxstrong}[1]{{\textbf{#1}}}
 % to obtain straight quotes we execute \@noligs as patched by upquote, the
 % macro must be robust in case it is used in captions e.g., and \scantokens is
@@ -165,9 +265,9 @@
 \newcommand{\sphinxcrossref}[1]{\emph{#1}}
 \newcommand{\sphinxtermref}[1]{\emph{#1}}
 
-% miscellaneous related to footnotes
+% Support large numbered footnotes in minipage
-\newcommand*{\sphinxAtStartFootnote}{\mbox{ }}
+% But now obsolete due to systematic use of \savenotes/\spewnotes
-% Support large numbered footnotes in minipage (cf. admonitions)
+% when minipages are in use in the various macro definitions next.
 \def\thempfootnote{\arabic{mpfootnote}}
 
 % Code-blocks
@@ -185,10 +285,6 @@
 \let\endOriginalVerbatim\endVerbatim
 
 \newif\ifspx@inframed % flag set if we are already in a framed environment
-\newdimen\sphinxverbatimsep   \sphinxverbatimsep   \fboxsep  % default 3pt
-\newdimen\sphinxverbatimborder\sphinxverbatimborder\fboxrule % default 0.4pt
-\newif\ifsphinxverbatimwithframe      \sphinxverbatimwithframetrue
-\newif\ifsphinxverbatimwrapslines     \sphinxverbatimwrapslinestrue
 % if forced use of minipage encapsulation is needed (e.g. table cells)
 \newif\ifsphinxverbatimwithminipage   \sphinxverbatimwithminipagefalse
 \newcommand\spx@colorbox [2]{%
@@ -266,6 +362,7 @@
 \newbox\sphinxvisiblespacebox
 % Customize this via 'preamble' key if desired.
 % Use of \textvisiblespace for compatibility with XeTeX/LuaTeX/fontspec.
+% FIXME: convert this to package options
 \newcommand*\sphinxvisiblespace {\textcolor{red}{\textvisiblespace}}
 \newcommand*\sphinxcontinuationsymbol {\textcolor{red}{\llap{\tiny$\m@th\hookrightarrow$}}}
 \newcommand*\sphinxcontinuationindent {3ex }
@@ -276,6 +373,7 @@
 %        {, <, #, %, $, ' and ": go to next line.
 %        _, }, ^, &, >, - and ~: stay at end of broken line.
 % Use of \textquotesingle for straight quote.
+% FIXME: convert this to package options
 \newcommand*\sphinxbreaksbeforelist {%
     \do\PYGZob\{\do\PYGZlt\<\do\PYGZsh\#\do\PYGZpc\%% {, <, #, %,
     \do\PYGZdl\$\do\PYGZdq\"% $, "
@@ -342,7 +440,7 @@
   \fi
   \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
   % setting borderwidth to zero is simplest for no-frame effect with same pagebreaks
-  \ifsphinxverbatimwithframe\else\fboxrule\z@\fi
+  \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
   % Customize framed.sty \MakeFramed to glue caption to literal block
   % via \spx@fcolorbox, will use \spx@VerbatimFBox which inserts title
   \def\FrameCommand   {\spx@colorbox\spx@fcolorbox }%
@@ -350,7 +448,7 @@
   % for mid pages and last page portion of (long) split frame:
   \def\MidFrameCommand{\spx@colorbox\fcolorbox }%
   \let\LastFrameCommand\MidFrameCommand
-  \ifsphinxverbatimwrapslines
+  \ifspx@opt@verbatimwrapslines
   % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
   % This customization wraps each line from the input in a \vtop, thus
   % allowing it to wrap and display on two or more lines in the latex output.
@@ -405,7 +503,7 @@
      % For grid placement from \strut's in \FancyVerbFormatLine
      \lineskip\z@skip
      % active comma should not be overwritten by \@noligs
-     \ifsphinxverbatimwrapslines
+     \ifspx@opt@verbatimwrapslines
        \let\verbatim@nolig@list \sphinx@verbatim@nolig@list
      \fi
      % will fetch its optional arguments if any
@@ -418,14 +516,14 @@
   \endtrivlist
 }
 \newenvironment {sphinxVerbatimNoFrame}
-  {\sphinxverbatimwithframefalse
+  {\spx@opt@verbatimwithframefalse
    % needed for fancyvrb as literal code will end in \end{sphinxVerbatimNoFrame}
    \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimNoFrame}}%
    \begin{sphinxVerbatim}}
   {\end{sphinxVerbatim}}
 \newenvironment {sphinxVerbatimintable}
   {% don't use a frame if in a table cell
-   \sphinxverbatimwithframefalse
+   \spx@opt@verbatimwithframefalse
    \sphinxverbatimwithminipagetrue
    % counteract longtable redefinition of caption
    \let\caption\sphinxfigcaption
@@ -438,15 +536,6 @@
 % Topic boxes
 
 % Again based on use of "framed.sty", this allows breakable framed boxes.
-
-% define macro to frame contents and add shadow on right and bottom
-% use public names for customizable lengths
-\newlength\sphinxshadowsep  \setlength\sphinxshadowsep  {5pt}
-\newlength\sphinxshadowsize \setlength\sphinxshadowsize {4pt}
-\newlength\sphinxshadowrule
-% this uses \fboxrule value at loading time of sphinx.sty (0.4pt normally)
-\setlength\sphinxshadowrule {\fboxrule}
-
 \long\def\spx@ShadowFBox#1{%
   \leavevmode\begingroup
   % first we frame the box #1
@@ -546,13 +635,13 @@
 % {fulllineitems} is the main environment for object descriptions.
 %
 \newcommand{\py@itemnewline}[1]{%
-  \@tempdima\linewidth%
+  \@tempdima\linewidth
   \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
 }
 
 \newenvironment{fulllineitems}{
-  \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
+  \begin{list}{}{\labelwidth \leftmargin \labelsep \z@
-                 \rightmargin 0pt \topsep -\parskip \partopsep \parskip
+                 \rightmargin \z@ \topsep -\parskip \partopsep \parskip
                  \itemsep -\parsep
                  \let\makelabel=\py@itemnewline}
 }{\end{list}}
@@ -573,14 +662,14 @@
 
 % Production lists
 %
-\newenvironment{productionlist}{
+\newenvironment{productionlist}{%
 %  \def\sphinxoptional##1{{\Large[}##1{\Large]}}
-  \def\production##1##2{\\\sphinxcode{##1}&::=&\sphinxcode{##2}}
+  \def\production##1##2{\\\sphinxcode{##1}&::=&\sphinxcode{##2}}%
-  \def\productioncont##1{\\& &\sphinxcode{##1}}
+  \def\productioncont##1{\\& &\sphinxcode{##1}}%
   \parindent=2em
   \indent
-  \setlength{\LTpre}{0pt}
+  \setlength{\LTpre}{0pt}%
-  \setlength{\LTpost}{0pt}
+  \setlength{\LTpost}{0pt}%
   \begin{longtable}[l]{lcl}
 }{%
   \end{longtable}
@@ -589,6 +678,7 @@
 % Notices / Admonitions
 
 % Some are quite plain
+% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
 \newenvironment{sphinxlightbox}{%
   \par\allowbreak
   \noindent{\color{spx@notice@bordercolor}%
@@ -614,25 +704,16 @@
   {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
 \newenvironment{sphinxtip}[1]
   {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
-% or user may just customize the bordercolor and the border width
+% or just use the package options
-% re-use \definecolor if change needed, and \renewcommand for rule width
-\definecolor{sphinxnotebordercolor}{rgb}{0,0,0}
-\definecolor{sphinxhintbordercolor}{rgb}{0,0,0}
-\definecolor{sphinximportantbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxtipbordercolor}{rgb}{0,0,0}
-\newcommand{\sphinxnoteborder}{0.5pt}
-\newcommand{\sphinxhintborder}{0.5pt}
-\newcommand{\sphinximportantborder}{0.5pt}
-\newcommand{\sphinxtipborder}{0.5pt}
 % these are needed for common handling by notice environment of lightbox
 % and heavybox but they are  currently not used by lightbox environment
+% and there is consequently no corresponding package option
 \definecolor{sphinxnotebgcolor}{rgb}{1,1,1}
 \definecolor{sphinxhintbgcolor}{rgb}{1,1,1}
 \definecolor{sphinximportantbgcolor}{rgb}{1,1,1}
 \definecolor{sphinxtipbgcolor}{rgb}{1,1,1}
 
 % Others get more distinction
-\newdimen\spx@notice@border
 % Code adapted from framed.sty's "snugshade" environment.
 % Nesting works (inner frames do not allow page breaks).
 \newenvironment{sphinxheavybox}{\par
@@ -689,22 +770,7 @@
   {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
 \newenvironment{sphinxerror}[1]
   {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
-% or just re-do \definecolor for colours, \renewcommand for frame width
+% or just use package options
-\definecolor{sphinxwarningbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxcautionbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxattentionbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxdangerbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxerrorbordercolor}{rgb}{0,0,0}
-\definecolor{sphinxwarningbgcolor}{rgb}{1,1,1}
-\definecolor{sphinxcautionbgcolor}{rgb}{1,1,1}
-\definecolor{sphinxattentionbgcolor}{rgb}{1,1,1}
-\definecolor{sphinxdangerbgcolor}{rgb}{1,1,1}
-\definecolor{sphinxerrorbgcolor}{rgb}{1,1,1}
-\newcommand{\sphinxwarningborder}{1pt}
-\newcommand{\sphinxcautionborder}{1pt}
-\newcommand{\sphinxattentionborder}{1pt}
-\newcommand{\sphinxdangerborder}{1pt}
-\newcommand{\sphinxerrorborder}{1pt}
 
 % the \colorlet of xcolor (if at all loaded) is overkill for our use case
 \newcommand{\sphinxcolorlet}[2]
@@ -721,7 +787,7 @@
   % set parameters of heavybox/lightbox
   \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1bordercolor}%
   \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1bgcolor}%
-  \setlength\spx@notice@border {\dimexpr\csname sphinx#1border\endcsname\relax}%
+  \spx@notice@border \dimexpr\csname sphinx#1border\endcsname\relax
   % start specific environment, passing the heading as argument
   \begin{sphinx#1}{#2}}
   % in end part, need to go around a LaTeX's "feature"
@@ -778,9 +844,9 @@
 % Redefine description environment so that it is usable inside fulllineitems.
 %
 \renewcommand{\description}{%
-  \list{}{\labelwidth\z@%
+  \list{}{\labelwidth\z@
-          \itemindent-\leftmargin%
+          \itemindent-\leftmargin
-	  \labelsep5pt%
+	  \labelsep5pt\relax
           \let\makelabel=\descriptionlabel}}
 
 % Definition lists; requested by AMK for HOWTO documents.  Probably useful
@@ -788,7 +854,7 @@
 %
 \newenvironment{definitions}{%
   \begin{description}%
-  \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}
+  \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
 }{%
   \end{description}%
 }
@@ -816,7 +882,7 @@
   {\setlength{\partopsep}{\parskip}
    \addtolength{\partopsep}{\baselineskip}
    \topsep0pt\itemsep0.15\baselineskip\parsep0pt
-   \leftmargin#1}
+   \leftmargin#1\relax}
  \raggedright}
 {\end{list}}
 
@@ -862,19 +928,26 @@
   \fi
 \fi
 
+% These options can be overriden inside  'hyperref' key
+% or by later use of \hypersetup.
+\PassOptionsToPackage{colorlinks,breaklinks,%
+ linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%
+ menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%
+ citecolor=InnerLinkColor}{hyperref}
+
 % From docutils.writers.latex2e
 % inline markup (custom roles)
 % \DUrole{#1}{#2} tries \DUrole#1{#2}
 \providecommand*{\DUrole}[2]{%
-  \ifcsname DUrole#1\endcsname%
+  \ifcsname DUrole#1\endcsname
     \csname DUrole#1\endcsname{#2}%
   \else% backwards compatibility: try \docutilsrole#1{#2}
-    \ifcsname docutilsrole#1\endcsname%
+    \ifcsname docutilsrole#1\endcsname
       \csname docutilsrole#1\endcsname{#2}%
-    \else%
+    \else
       #2%
-    \fi%
+    \fi
-  \fi%
+  \fi
 }
 
 \providecommand*{\DUprovidelength}[2]{%
@@ -987,6 +1060,7 @@
 \fi
 
 % additional customizable styling
+% FIXME: convert this to package options ?
 \newcommand*{\sphinxstyleindexentry}{\texttt}
 \newcommand{\sphinxstyleindexextra}[1]{ \emph{(#1)}}
 \newcommand*{\sphinxstyleindexpageref}{, \pageref}

sphinx/writers/latex.py

@@ -52,6 +52,7 @@ DEFAULT_SETTINGS = {
     'classoptions':    '',
     'extraclassoptions': '',
     'maxlistdepth':    '',
+    'sphinxpackageoptions': '',
     'passoptionstopackages': '',
     'geometry':        '\\usepackage[margin=1in,marginparwidth=0.5in]'
                        '{geometry}',
@@ -69,13 +70,7 @@ DEFAULT_SETTINGS = {
     'fncychap':        '\\usepackage[Bjarne]{fncychap}',
     'longtable':       '\\usepackage{longtable}',
     'hyperref':        ('% Include hyperref last.\n'
-                        '\\usepackage[colorlinks,breaklinks,%\n'
+                        '\\usepackage{hyperref}\n'
-                        '            '
-                        'linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%\n'
-                        '            '
-                        'menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%\n'
-                        '            '
-                        'citecolor=InnerLinkColor]{hyperref}\n'
                         '% Fix anchor placement for figures with captions.\n'
                         '\\usepackage{hypcap}% it must be loaded after hyperref.\n'
                         '% Set up styles of URL: it should be placed after hyperref.\n'
@@ -377,7 +372,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         })
         sphinxpkgoptions = ''
         if not builder.config.latex_keep_old_macro_names:
-            sphinxpkgoptions = 'dontkeepoldnames'
+            sphinxpkgoptions = ',dontkeepoldnames'
         if document.settings.docclass == 'howto':
             docclass = builder.config.latex_docclass.get('howto', 'article')
         else:
@@ -454,8 +449,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if self.elements['maxlistdepth']:
             sphinxpkgoptions += ',maxlistdepth=%s' % self.elements['maxlistdepth']
         if sphinxpkgoptions:
-            self.elements['passoptionstosphinx'] = \
+            self.elements['sphinxpackageoptions'] += sphinxpkgoptions
-                '\\PassOptionsToPackage{%s}{sphinx}' % sphinxpkgoptions
         if self.elements['extraclassoptions']:
             self.elements['classoptions'] += ',' + \
                                              self.elements['extraclassoptions']