diff --git a/doc/config.rst b/doc/config.rst index 737f01379..c34f71db1 100644 --- a/doc/config.rst +++ b/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'`` diff --git a/doc/latex.rst b/doc/latex.rst index 1716a5af4..555b04483 100644 --- a/doc/latex.rst +++ b/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 -: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 ` 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[]{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{}``, 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`` with ```` 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 ```` one of - :dudir:`warning`, :dudir:`caution`, :dudir:`attention`, - :dudir:`danger`, :dudir:`error`, the colours - *sphinxbordercolor* and *sphinxbgcolor* can be - re-defined using ``\definecolor`` command. The - ``\sphinxborder`` 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 ```` 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 ````, the used environment is named ``sphinx``. 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 diff --git a/sphinx/templates/latex/content.tex_t b/sphinx/templates/latex/content.tex_t index 87792e2ce..f63fac6d1 100644 --- a/sphinx/templates/latex/content.tex_t +++ b/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 %> diff --git a/sphinx/texinputs/footnotehyper-sphinx.sty b/sphinx/texinputs/footnotehyper-sphinx.sty index 65cb6e8bc..a714f211d 100644 --- a/sphinx/texinputs/footnotehyper-sphinx.sty +++ b/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 -%% 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'. diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 1ff11fe89..ce4088e91 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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. -\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} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 73925791a..4ffafc66e 100644 --- a/sphinx/writers/latex.py +++ b/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' - ' ' - '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']