IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
jfbu 2016-10-27 20:24:33 +02:00
parent 99147c1372
commit fb8bb072cb
6 changed files with 360 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/config.rst
View File

@ -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'``

244
doc/latex.rst
View File

@ -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
:file:`mycustomizedmacros.sty`, which can then be loaded via::
or, better, to set up a style file
: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
from package file :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
:file:`sphinxmanual.cls`, and can be customized.
The ``'sphinxpackageoptions'`` key to :confval:`latex_elements` provides a
more convenient interface to various style parameters. It is a comma separated
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
: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
- paragraph level environments: for each admonition type ``<foo>``, 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:
``\sphinxshadowsep`` (distance from contents), ``\sphinxshadowsize`` (width of
lateral shadow), ``\sphinxshadowrule`` (thickness of the frame).
See above for the three dimensions associated with it.
.. 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
``\sphinxverbatimborder`` customize the framing. Inside tables the used
pagebreaks. 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

3
sphinx/templates/latex/content.tex_t
View File

@ -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 %>

28
sphinx/texinputs/footnotehyper-sphinx.sty
View File

@ -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
%% 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.
%%
%% 4. \sphinxfootnotemark, and use of \spx@opt@BeforeFootnote from sphinx.sty.
%% 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
\def\FNH@fixed@footnote {\sphinxBeforeFootnote\ifx\@currenvir\fn@footnote
%% \spx@opt@BeforeFootnote is defined in sphinx.sty
\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'.

232
sphinx/texinputs/sphinx.sty
View File

@ -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.
\definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
\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}
% Initialize style parameters
\sphinx@setup
% 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{\sphinxSetHeaderFamily}[1]{\renewcommand{\py@HeaderFamily}{#1}}
\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily}
% 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
\newcommand*{\sphinxAtStartFootnote}{\mbox{ }}
% Support large numbered footnotes in minipage (cf. admonitions)
% Support large numbered footnotes in minipage
% But now obsolete due to systematic use of \savenotes/\spewnotes
% 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
\rightmargin 0pt \topsep -\parskip \partopsep \parskip
\begin{list}{}{\labelwidth \leftmargin \labelsep \z@
\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\productioncont##1{\\& &\sphinxcode{##1}}
\def\production##1##2{\\\sphinxcode{##1}&::=&\sphinxcode{##2}}%
\def\productioncont##1{\\& &\sphinxcode{##1}}%
\parindent=2em
\indent
\setlength{\LTpre}{0pt}
\setlength{\LTpost}{0pt}
\setlength{\LTpre}{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
% 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}
% or just use the package options
% 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
\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}
% or just use package options
% 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@%
\itemindent-\leftmargin%
\labelsep5pt%
\list{}{\labelwidth\z@
\itemindent-\leftmargin
\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}

14
sphinx/writers/latex.py
View File

@ -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'
' '
'linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%\n'
' '
'menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%\n'
' '
'citecolor=InnerLinkColor]{hyperref}\n'
'\\usepackage{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'] = \
'\\PassOptionsToPackage{%s}{sphinx}' % sphinxpkgoptions
self.elements['sphinxpackageoptions'] += sphinxpkgoptions
if self.elements['extraclassoptions']:
self.elements['classoptions'] += ',' + \
self.elements['extraclassoptions']