diff --git a/doc/latex.rst b/doc/latex.rst index 594f0424918..506d5127375 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1210,17 +1210,12 @@ which is then followed by an underscore, then the property name. :dudir:`note`, ``div.note``, ``sphinxnote`` :dudir:`warning`, ``div.warning``, ``sphinxwarning`` further admonition types ````, ``div.``, ``sphinx`` - :dudir:`seealso`, ``div.seealso``, ``sphinxseealso`` + :rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso`` + :rst:dir:`todo`, ``div.todo``, ``sphinxtodo`` -.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` directive. - -.. todo:: - - Currently the ``todo`` directive from the eponymous extension is rendered - in LaTeX as if it were a :dudir:`note` directive with title ``Todo``. In - future, it should acquire its independence via better mark-up in the LaTeX - output. +.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and + :rst:dir:`todo` directives. Here are now these options as well as their common defaults. Replace below ```` by the actual prefix as explained above. Don't @@ -1238,6 +1233,7 @@ forget the underscore separating the prefix from the property names. * ``0.4pt`` for :rst:dir:`code-block`, * ``0.5pt`` for :dudir:`topic` or contents_ directive, * ``0.5pt`` for :dudir:`note` and other "light" admonitions, + * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, * ``1.5pt`` for :dudir:`warning` and other "strong" admonitions except for :dudir:`error`: ``2pt`` for :dudir:`error`. @@ -1260,7 +1256,8 @@ forget the underscore separating the prefix from the property names. * all four ``3pt`` for :rst:dir:`code-block`, * ``10pt``, ``12pt``, ``12pt``, ``12pt`` for :dudir:`topic` or contents_ directive, - * ``6pt``, ``12pt``, ``6pt``, ``12pt`` for all admonition types. + * ``6pt``, ``12pt``, ``6pt``, ``12pt`` for all admonition types as well + as :rst:dir:`seealso` and :rst:dir:`todo` directives. .. versionchanged:: 7.4.0 @@ -1569,6 +1566,7 @@ Macros ``\sphinxstyledangertitle``; *similar* ``\sphinxstyleerrortitle``; *similar* ``\sphinxstyleseealsotitle``; *similar* + ``\sphinxstyleseetodotitle``; *similar* .. note:: @@ -1789,6 +1787,11 @@ Environments Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally. +- Environment for the :rst:dir:`todo` directive: ``sphinxtodo``. + It takes one argument which will be the localized string ``Todo`` + followed with a colon. + + .. versionadded:: 7.4.0 - The contents_ directive (with ``:local:`` option) and the :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index 1962328d766..94473e7b838 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -209,7 +209,7 @@ def depart_todo_node(self: HTML5Translator, node: todo_node) -> None: def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None: if self.config.todo_include_todos: - self.body.append('\n\\begin{sphinxadmonition}{note}{') + self.body.append('\n\\begin{sphinxtodo}{') self.body.append(self.hypertarget_to(node)) title_node = cast(nodes.title, node[0]) @@ -221,7 +221,7 @@ def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None: def latex_depart_todo_node(self: LaTeXTranslator, node: todo_node) -> None: - self.body.append('\\end{sphinxadmonition}\n') + self.body.append('\\end{sphinxtodo}\n') def setup(app: Sphinx) -> ExtensionMetadata: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 4f662e5d515..1cb98c804a9 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -276,6 +276,7 @@ % % seealso directive is also using "heavybox" at 7.4.0 acquiring the same % customizability as admonitions. +% todo directive also. \definecolor{sphinx-admonition-bgcolor} {RGB}{247, 247, 247}% #F7F7F7 \definecolor{sphinx-admonition-bordercolor} {RGB}{134, 152, 155}% #86989B \definecolor{sphinx-warning-bordercolor} {RGB}{148, 0, 0}% #940000 @@ -284,12 +285,14 @@ \spx@DeclareColorOption[sphinx]{importantBorderColor}{sphinx-admonition-bordercolor} \spx@DeclareColorOption[sphinx]{tipBorderColor} {sphinx-admonition-bordercolor} \spx@DeclareColorOption[sphinx]{seealsoBorderColor} {sphinx-admonition-bordercolor}% 7.4.0 +\spx@DeclareColorOption[sphinx]{todoBorderColor} {sphinx-admonition-bordercolor}% 7.4.0 % \spx@DeclareColorOption[sphinx]{noteBgColor} {sphinx-admonition-bgcolor} \spx@DeclareColorOption[sphinx]{hintBgColor} {sphinx-admonition-bgcolor} \spx@DeclareColorOption[sphinx]{importantBgColor}{sphinx-admonition-bgcolor} \spx@DeclareColorOption[sphinx]{tipBgColor} {sphinx-admonition-bgcolor} \spx@DeclareColorOption[sphinx]{seealsoBgColor} {sphinx-admonition-bgcolor}% 7.4.0 +\spx@DeclareColorOption[sphinx]{todoBgColor} {sphinx-admonition-bgcolor}% 7.4.0 % \spx@DeclareColorOption[sphinx]{warningBorderColor} {sphinx-warning-bordercolor} \spx@DeclareColorOption[sphinx]{cautionBorderColor} {sphinx-warning-bordercolor} @@ -343,7 +346,8 @@ % legacy styles. At 7.4.0, as a follow-up to the revamped styles of % admonitions in the HTML sphinx13 theme (PR #12439), it is decided to % apply similar styling for PDF output. Also the seealso directive -% is handled as an admonition with the same customizability. +% is handled as an admonition with the same customizability. And the +% todo directive. % \def\spxstring@none{none} \def\spxstring@clone{clone} @@ -397,6 +401,7 @@ \spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt} \spx@tempa{spx@tip@} {div.tip_} {tipborder} {0.5pt} \spx@tempa{spx@seealso@} {div.seealso_} {seealsoborder} {0.5pt}% new at 7.4.0 +\spx@tempa{spx@todo@} {div.todo_} {todoborder} {0.5pt}% new at 7.4.0 \spx@tempa{spx@warning@} {div.warning_} {warningborder} {1.5pt}% mod. at 7.4.0 \spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1.5pt}% mod. at 7.4.0 \spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1.5pt}% mod. at 7.4.0 @@ -447,6 +452,7 @@ \spx@tempa{spx@important@}{div.important_} {6pt}{12pt}{6pt}{12pt} \spx@tempa{spx@tip@} {div.tip_} {6pt}{12pt}{6pt}{12pt} \spx@tempa{spx@seealso@} {div.seealso_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@todo@} {div.todo_} {6pt}{12pt}{6pt}{12pt} \spx@tempa{spx@warning@} {div.warning_} {6pt}{11pt}{6pt}{11pt} \spx@tempa{spx@caution@} {div.caution_} {6pt}{11pt}{6pt}{11pt} \spx@tempa{spx@attention@}{div.attention_} {6pt}{11pt}{6pt}{11pt} @@ -492,6 +498,7 @@ \spx@tempa{spx@important@}{div.important_} \z@\z@\z@\z@ \spx@tempa{spx@tip@} {div.tip_} {5pt}{5pt}{5pt}{5pt} \spx@tempa{spx@seealso@} {div.seealso_} \z@\z@\z@\z@ +\spx@tempa{spx@todo@} {div.todo_} \z@\z@\z@\z@ \spx@tempa{spx@warning@} {div.warning_} \z@\z@\z@\z@ \spx@tempa{spx@caution@} {div.caution_} \z@\z@\z@\z@ \spx@tempa{spx@attention@}{div.attention_} \z@\z@\z@\z@ @@ -519,6 +526,7 @@ \spx@tempa{spx@important@} \spx@tempa{spx@tip@} \spx@tempa{spx@seealso@}% 7.4.0 +\spx@tempa{spx@todo@}% 7.4.0 \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -567,6 +575,7 @@ \spx@tempa{spx@important@}{div.important_} \spx@tempa{spx@tip@} {div.tip_} \spx@tempa{spx@seealso@} {div.seealso_} +\spx@tempa{spx@todo@} {div.todo_} \spx@tempa{spx@warning@} {div.warning_} \spx@tempa{spx@caution@} {div.caution_} \spx@tempa{spx@attention@}{div.attention_} @@ -633,6 +642,7 @@ \spx@tempa{spx@important@} \spx@tempa{spx@tip@} \spx@tempa{spx@seealso@} +\spx@tempa{spx@todo@} \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -647,7 +657,7 @@ \csname #1TeXextras\endcsname } % 7.4.0 adds options for a title. They have an action only for admonitions, -% and seealso. +% seealso and todo directives. \def\spx@tempb#1#2#3#4#5{% #4 = option prefix, #5 = color name prefix \define@key{sphinx}{#4border-TeXcolor}% {\spx@defineorletcolor{#5BorderColor}##1\relax}% @@ -685,6 +695,7 @@ \spx@tempa{spx@important@}{div.important_} {sphinximportant} \spx@tempa{spx@tip@} {div.tip_} {sphinxtip} \spx@tempa{spx@seealso@} {div.seealso_} {sphinxseealso} +\spx@tempa{spx@todo@} {div.todo_} {sphinxtodo} \spx@tempa{spx@warning@} {div.warning_} {sphinxwarning} \spx@tempa{spx@caution@} {div.caution_} {sphinxcaution} \spx@tempa{spx@attention@}{div.attention_} {sphinxattention} @@ -755,15 +766,8 @@ \definecolor{sphinx-success-title-fgcolor} {RGB}{81,174,128} % hsl(150, 36.7%, 50%); \definecolor{sphinx-error-title-bgcolor} {RGB}{238,220,220} % hsl(0, 37%, 90%); \definecolor{sphinx-error-title-fgcolor} {RGB}{174,80,80} % hsl(0, 37%, 50%); -%% -%% TODO: support todo (sic). -%% Currently the LaTeX mark-up is -%% \begin{sphinxadmonition}{note}{Todo:} and actually even worse -%% \begin{sphinxadmonition}{note}{\label{some tag}Todo:} but the \label -%% can not work correctly as there is no target from a LaTeX counter. -%% -%%\definecolor{sphinx-todo-title-bgcolor} {RGB}{226,204,254} % hsl(266.8, 100%, 90%); -%%\definecolor{sphinx-todo-title-fgcolor} {RGB}{113,0,255} % hsl(266.8, 100%, 50%); +\definecolor{sphinx-todo-title-bgcolor} {RGB}{226,204,254} % hsl(266.8, 100%, 90%); +\definecolor{sphinx-todo-title-fgcolor} {RGB}{113,0,255} % hsl(266.8, 100%, 50%); % Now use the above colours as default settings, following the choices % done in sphinx13.css @@ -777,6 +781,8 @@ div.tip_title-foreground-TeXcolor=sphinx-success-title-fgcolor, div.seealso_title-background-TeXcolor=sphinx-success-title-bgcolor, div.seealso_title-foreground-TeXcolor=sphinx-success-title-fgcolor, + div.todo_title-background-TeXcolor=sphinx-todo-title-bgcolor, + div.todo_title-foreground-TeXcolor=sphinx-todo-title-fgcolor, % div.important_title-background-TeXcolor=sphinx-warning-title-bgcolor, div.important_title-foreground-TeXcolor=sphinx-warning-title-fgcolor, @@ -844,6 +850,9 @@ \ifdefined\faicon@radiation\else \let\faicon@radiation\faBolt \fi + \ifdefined\faicon@pen\else + \let\faicon@pen\faPencil + \fi % if neither has been required, \spx@faIcon will simply swallow % its argument (and follwing space macro) and it is up to user % to set the keys appropriately. @@ -864,6 +873,7 @@ div.hint_title-icon = \spx@faIcon[regular]{lightbulb}, div.tip_title-icon = \spx@faIcon[regular]{lightbulb}, div.seealso_title-icon = \spx@faIcon{share}, + div.todo_title-icon = \spx@faIcon{pen}, div.important_title-icon = \spx@faIcon{pause-circle}, div.caution_title-icon = \spx@faIcon{radiation}, div.warning_title-icon = \spx@faIcon{exclamation-triangle}, diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index fcdfaa794f1..3ecd8b59743 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -10,6 +10,8 @@ % At 7.4.0 it too now uses sphinxheavybox, and has the same associated % sphinxsetup CSS keys as admonitions do. % +% - sphinxtodo environment added at 7.4.0. +% % - sphinxadmonition (environment) % This is a dispatch which formerly configured % @@ -31,6 +33,12 @@ % The sphinxlightbox environment is kept for backward compatiblity, for user % custom code which used it via custom definitions done in preamble or via % raw latex directive. +% MEMO: here is for example how sphinxnote was formerly defined: +% \newenvironment{sphinxnote}[1] +% {\begin{sphinxlightbox}\sphinxstylenotetitle{#1}} +% {\end{sphinxlightbox}} +% Use this if you want to revert the 7.4.0 switch to usage of sphinxheavybox. + % % Requires: \RequirePackage{sphinxpackageboxes} @@ -89,7 +97,7 @@ % the former \sphinxstrong{#1} used a too generic \sphinxstrong. % % At 7.4.0, sphinxheavybox environment is default for all types of notices -% and also for seealso directive. +% and also for the seealso and todo directives. % % Code adapted from framed.sty's "snugshade" environment. % Nesting works (inner frames do not allow page breaks). @@ -248,6 +256,17 @@ \spx@seealso@TeXextras } {\end{sphinxheavybox}} +% There was no sphinxtodo environment until 7.4.0 because sphinx.ext.todo +% generated \begin{sphinxadmonition}{note}{Todo:} mark-up. +\newcounter{sphinxtodo}% to provide targets from todolist directive output +\newenvironment{sphinxtodo}[1] + {\refstepcounter{sphinxtodo}\def\spx@noticetype{todo}% + \begin{sphinxheavybox}\sphinxstyletodotitle{#1}% + \ifspx@todo@withtextcolor\color{sphinxtodoTextColor}\fi + \spx@todo@TeXextras + } + {\end{sphinxheavybox}} + % the main dispatch for all types of notices \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading @@ -335,6 +354,7 @@ \newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}} \newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}} \newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerowwithicon{todo}{\sphinxremovefinalcolon{#1}}} % % A utility to remove a final colon. Removing last token is not easy in % LaTeX, and there are additional complications: