mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #2685 from jfbu/jfbu_customizablenotices
latex: fully customizable notices/admonitions
This commit is contained in:
Jean-François B
GitHub
commit
452c8b162c
3
CHANGES
3
CHANGES
@ -30,6 +30,9 @@ Features added
|
||||
the ``visit_emphasis`` will output ``\sphinxstyleemphasis`` rather than
|
||||
``\emph`` (which may be in use elsewhere or in an added LaTeX package). See
|
||||
list at end of ``sphinx.sty`` (ref: #2686)
|
||||
* public names for latex environments and parameters used by note, warning,
|
||||
and other admonition types, allowing full customizability from the
|
||||
``'preamble'`` key (ref: feature request #2674, #2685)
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
@ -1460,7 +1460,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
Options for LaTeX output
|
||||
------------------------
|
||||
|
||||
These options influence LaTeX output.
|
||||
These options influence LaTeX output. See further :doc:`latex`.
|
||||
|
||||
.. confval:: latex_documents
|
||||
|
||||
@ -1623,7 +1623,7 @@ These options influence LaTeX output.
|
||||
|
||||
.. versionadded:: 1.4
|
||||
``'preamble'``
|
||||
Additional preamble content, default empty.
|
||||
Additional preamble content, default empty. See :doc:`latex`.
|
||||
``'figure_align'``
|
||||
Latex figure float alignment, default 'htbp' (here, top, bottom, page).
|
||||
Whenever an image doesn't fit into the current page, it will be
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
|
||||
.. _contents:
|
||||
|
||||
Sphinx documentation contents
|
||||
@ -17,6 +18,7 @@ Sphinx documentation contents
|
||||
intl
|
||||
theming
|
||||
templating
|
||||
latex
|
||||
extensions
|
||||
extdev/index
|
||||
websupport
|
||||
|
||||
126
doc/latex.rst
Normal file
126
doc/latex.rst
Normal file
@ -0,0 +1,126 @@
|
||||
.. highlightlang:: python
|
||||
|
||||
.. _latex:
|
||||
|
||||
LaTeX customization
|
||||
===================
|
||||
|
||||
.. module:: latex
|
||||
:synopsis: LaTeX specifics.
|
||||
|
||||
The *latex* target does not (yet) benefit from pre-prepared themes like the
|
||||
*html* target does (see :doc:`theming`).
|
||||
|
||||
There are two principal means of setting up customization:
|
||||
|
||||
#. usage of the :ref:`latex-options` as described in :doc:`config`, particularly the
|
||||
various keys of :confval:`latex_elements`, to modify the loaded packages,
|
||||
for example::
|
||||
|
||||
'fontpkg': '\\usepackage{times}', # can load other font
|
||||
'fncychap': '\\usepackage[Bjarne]{fncychap}', # can use other option
|
||||
|
||||
.. tip::
|
||||
|
||||
It is not mandatory to load *fncychap*. Naturally, without it and in
|
||||
absence of further customizations, the chapter headings will revert to
|
||||
LaTeX's default for the *report* class.
|
||||
|
||||
#. usage of LaTeX ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
|
||||
``\definecolor`` to modify the defaults from package file :file:`sphinx.sty`
|
||||
and class files :file:`sphinxhowto.cls` and :file:`sphinxmanual.cls`. If such
|
||||
definitions are few, they can be located inside the ``'preamble'`` key of
|
||||
:confval:`latex_elements`. In case of many it may prove more convenient to
|
||||
assemble them into a specialized file :file:`customizedmacros.tex` and use::
|
||||
|
||||
'preamble': '\\makeatletter\\input{customizedmacros.tex}\\makeatother',
|
||||
|
||||
More advanced LaTeX users will set up a style file
|
||||
:file:`customizedmacros.sty`, which can then be loaded via::
|
||||
|
||||
'preamble': '\\usepackage{customizedmacros}',
|
||||
|
||||
The :ref:`build configuration file <build-config>` file will then have its variable
|
||||
:confval:`latex_additional_files` appropriately configured, for example::
|
||||
|
||||
latex_additional_files = ["customizedmacros.sty"]
|
||||
|
||||
Such *LaTeX Sphinx theme* files could possibly be contributed in the
|
||||
future by advanced users for wider use.
|
||||
|
||||
Let us illustrate here what can be modified by the second method.
|
||||
|
||||
- text styling commands (they have one argument): ``\sphinx<foo>`` with
|
||||
``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
|
||||
``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
|
||||
``optional``. By default and for backwards compatibility the ``\sphinx<foo>``
|
||||
expands to ``\<foo>`` hence the user can choose to customize rather the latter
|
||||
(the non-prefixed macros will be left undefined if option
|
||||
:confval:`latex_keep_old_macro_names` is set to ``False`` in :file:`conf.py`.)
|
||||
|
||||
.. versionchanged:: 1.4.5
|
||||
use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
|
||||
with user added packages. The LaTeX writer uses always the prefixed names.
|
||||
- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
|
||||
``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
|
||||
``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
|
||||
``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
|
||||
``abbreviation``, ``literalintitle``.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
earlier, the LaTeX writer used hard-coded ``\texttt``, ``\emph``, etc...
|
||||
- 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
|
||||
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.
|
||||
|
||||
.. 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).
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
use of public names for the three lengths. The environment itself was
|
||||
redefined to allow page breaks at release 1.4.2.
|
||||
- miscellaneous colours: *TitleColor*, *InnerLinkColor*, *OuterLinkColor*,
|
||||
*VerbatimColor* (this is a background colour), *VerbatimBorderColor*.
|
||||
- the ``\sphinxAtStartFootnote`` is inserted between footnote numbers and their
|
||||
texts, by default it does ``\mbox{ }``.
|
||||
- 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.
|
||||
- for the ``'manual'`` class, the chapter headings can be customized using
|
||||
*fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. Or, if
|
||||
the loading of this package has been removed from ``'fncychap'`` key, one can
|
||||
use the *titlesec* ``\titleformat`` command.
|
||||
|
||||
.. note::
|
||||
|
||||
It is impossible to revert or prevent the loading of a package that results
|
||||
from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
|
||||
file. Sphinx aims at loading as few packages as are really needed for its
|
||||
default design.
|
||||
@ -540,12 +540,56 @@
|
||||
}
|
||||
|
||||
% Notices / Admonitions
|
||||
%
|
||||
|
||||
% Some are quite plain
|
||||
\newenvironment{sphinxlightbox}{%
|
||||
\par\allowbreak
|
||||
\noindent{\color{spx@notice@bordercolor}%
|
||||
\rule{\linewidth}{\spx@notice@border}}\par\nobreak
|
||||
{\parskip\z@skip\noindent}%
|
||||
}
|
||||
{%
|
||||
\par
|
||||
% counteract previous possible negative skip (French lists!):
|
||||
% (we can't cancel that any earlier \vskip introduced a potential pagebreak)
|
||||
\ifdim\lastskip<\z@\vskip-\lastskip\fi
|
||||
\nobreak\vbox{\noindent\kern\@totalleftmargin
|
||||
{\color{spx@notice@bordercolor}%
|
||||
\rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
|
||||
{\linewidth}{\spx@notice@border}}\hss}\allowbreak
|
||||
}% end of sphinxlightbox environment definition
|
||||
% may be renewenvironment'd by user for complete customization
|
||||
\newenvironment{sphinxnote}[1]
|
||||
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
|
||||
\newenvironment{sphinxhint}[1]
|
||||
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
|
||||
\newenvironment{sphinximportant}[1]
|
||||
{\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}
|
||||
% these are needed for common handling by notice environment of lightbox
|
||||
% and heavybox but they are currently not used by lightbox environment
|
||||
\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).
|
||||
\newcommand{\py@heavybox}{\par
|
||||
\setlength{\FrameRule}{\p@}% 1pt
|
||||
\newenvironment{sphinxheavybox}{\par
|
||||
\setlength{\FrameRule}{\spx@notice@border}%
|
||||
\setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax}
|
||||
% configure framed.sty's parameters to obtain same vertical spacing
|
||||
% as for "light" boxes. We need for this to manually insert parskip glue and
|
||||
@ -554,7 +598,8 @@
|
||||
\vspace{\FrameHeightAdjust}
|
||||
% copied/adapted from framed.sty's snugshade
|
||||
\def\FrameCommand##1{\hskip\@totalleftmargin
|
||||
\fboxsep\FrameSep \fboxrule\FrameRule\fbox{##1}%
|
||||
\fboxsep\FrameSep \fboxrule\FrameRule
|
||||
\fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}%
|
||||
\hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
|
||||
% use a minipage if we are already inside a framed environment
|
||||
\ifspx@inframed
|
||||
@ -578,7 +623,7 @@
|
||||
\@minipagerestore
|
||||
\@setminipage }%
|
||||
}
|
||||
\newcommand{\py@endheavybox}{%
|
||||
{%
|
||||
\par\unskip
|
||||
% handles footnotes
|
||||
\ifvoid\@mpfootins\else
|
||||
@ -589,49 +634,55 @@
|
||||
\ifspx@inframed\end{minipage}\fi
|
||||
% arrange for similar spacing below frame as for "light" boxes.
|
||||
\vskip .4\baselineskip
|
||||
}
|
||||
}% end of sphinxheavybox environment definition
|
||||
% may be renewenvironment'd by user for complete customization
|
||||
\newenvironment{sphinxwarning}[1]
|
||||
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
|
||||
\newenvironment{sphinxcaution}[1]
|
||||
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
|
||||
\newenvironment{sphinxattention}[1]
|
||||
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
|
||||
\newenvironment{sphinxdanger}[1]
|
||||
{\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}
|
||||
|
||||
\newcommand{\py@lightbox}{%
|
||||
\par\allowbreak
|
||||
\noindent\rule{\linewidth}{0.5pt}\par\nobreak
|
||||
{\parskip\z@skip\noindent}%
|
||||
}
|
||||
\newcommand{\py@endlightbox}{%
|
||||
\par
|
||||
% counteract previous possible negative skip (French lists!):
|
||||
% (we can't cancel that any earlier \vskip introduced a potential pagebreak)
|
||||
\ifdim\lastskip<\z@\vskip-\lastskip\fi
|
||||
\nobreak\vbox{\noindent\kern\@totalleftmargin
|
||||
\rule[.4\baselineskip]{\linewidth}{0.5pt}\hss}\allowbreak
|
||||
}
|
||||
% the \colorlet of xcolor (if at all loaded) is overkill for our use case
|
||||
\newcommand{\sphinxcolorlet}[2]
|
||||
{\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname
|
||||
\csname\@backslashchar color@#2\endcsname }
|
||||
|
||||
% Some are quite plain:
|
||||
\newcommand{\py@noticestart@note}{\py@lightbox}
|
||||
\newcommand{\py@noticeend@note}{\py@endlightbox}
|
||||
\newcommand{\py@noticestart@hint}{\py@lightbox}
|
||||
\newcommand{\py@noticeend@hint}{\py@endlightbox}
|
||||
\newcommand{\py@noticestart@important}{\py@lightbox}
|
||||
\newcommand{\py@noticeend@important}{\py@endlightbox}
|
||||
\newcommand{\py@noticestart@tip}{\py@lightbox}
|
||||
\newcommand{\py@noticeend@tip}{\py@endlightbox}
|
||||
|
||||
% Others gets more visible distinction:
|
||||
\newcommand{\py@noticestart@warning}{\py@heavybox}
|
||||
\newcommand{\py@noticeend@warning}{\py@endheavybox}
|
||||
\newcommand{\py@noticestart@caution}{\py@heavybox}
|
||||
\newcommand{\py@noticeend@caution}{\py@endheavybox}
|
||||
\newcommand{\py@noticestart@attention}{\py@heavybox}
|
||||
\newcommand{\py@noticeend@attention}{\py@endheavybox}
|
||||
\newcommand{\py@noticestart@danger}{\py@heavybox}
|
||||
\newcommand{\py@noticeend@danger}{\py@endheavybox}
|
||||
\newcommand{\py@noticestart@error}{\py@heavybox}
|
||||
\newcommand{\py@noticeend@error}{\py@endheavybox}
|
||||
|
||||
\newenvironment{notice}[2]{
|
||||
\def\py@noticetype{#1}
|
||||
\csname py@noticestart@#1\endcsname
|
||||
\sphinxstrong{#2} % <- legacy code creates a space after {#2}
|
||||
}{\csname py@noticeend@\py@noticetype\endcsname}
|
||||
% the main dispatch for all types of notices
|
||||
\newenvironment{sphinxadmonition}{\begin{notice}}{\end{notice}}
|
||||
% use of ``notice'' is for backwards compatibility and will be removed in
|
||||
% future release; sphinxadmonition environment will be defined directly.
|
||||
\newenvironment{notice}[2]{% #1=type, #2=heading
|
||||
% can't use #1 directly in definition of end part
|
||||
\def\spx@noticetype {#1}%
|
||||
% 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}%
|
||||
% start specific environment, passing the heading as argument
|
||||
\begin{sphinx#1}{#2}}
|
||||
% in end part, need to go around a LaTeX's "feature"
|
||||
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
|
||||
|
||||
% Allow the release number to be specified independently of the
|
||||
% \date{}. This allows the date to reflect the document's date and
|
||||
|
||||
@ -1533,19 +1533,19 @@ class LaTeXTranslator(nodes.NodeVisitor):
|
||||
self.body.append('}')
|
||||
|
||||
def visit_admonition(self, node):
|
||||
self.body.append('\n\\begin{notice}{note}')
|
||||
self.body.append('\n\\begin{sphinxadmonition}{note}')
|
||||
|
||||
def depart_admonition(self, node):
|
||||
self.body.append('\\end{notice}\n')
|
||||
self.body.append('\\end{sphinxadmonition}\n')
|
||||
|
||||
def _make_visit_admonition(name):
|
||||
def visit_admonition(self, node):
|
||||
self.body.append(u'\n\\begin{notice}{%s}{%s:}' %
|
||||
self.body.append(u'\n\\begin{sphinxadmonition}{%s}{%s:}' %
|
||||
(name, admonitionlabels[name]))
|
||||
return visit_admonition
|
||||
|
||||
def _depart_named_admonition(self, node):
|
||||
self.body.append('\\end{notice}\n')
|
||||
self.body.append('\\end{sphinxadmonition}\n')
|
||||
|
||||
visit_attention = _make_visit_admonition('attention')
|
||||
depart_attention = _depart_named_admonition
|
||||
|
||||
Loading…
Reference in New Issue
Block a user