Skip to content

Commit

Permalink
Style admonitions with tcolorbox in LaTeXWriter (#1932)
Browse files Browse the repository at this point in the history
  • Loading branch information
odow authored Sep 20, 2022
1 parent ceab61d commit 674c02e
Show file tree
Hide file tree
Showing 5 changed files with 75 additions and 78 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

**For upgrading:** The cases where an `@eval` results in a object that is not `nothing` or `::Markdown.MD`, the returned object should be reviewed. In case the resulting object is of some `Markdown` node type (e.g. `Markdown.Paragraph` or `Markdown.Table`), it can simply be wrapped in `Markdown.MD([...])` for block nodes, or `Markdown.MD([Markdown.Paragraph([...])])` for inline nodes. In other cases Documenter was likely not handling the returned object in a correct way, but please open an issue if this change has broken a previously working use case.

* ![Enhancement][badge-enhancement] Admonitions are now styled with color in the LaTeX output. ([#1931][github-1931], [#1932][github-1932])
* ![Enhancement][badge-enhancement] Improved the styling of code blocks in the LaTeXWriter. ([#1933][github-1933], [#1935][github-1935])
* ![Enhancement][badge-enhancement] The `ansicolor` keyword to `HTML()` now defaults to true, meaning that executed outputs from `@example`- and `@repl`-blocks are now by default colored (if they emit colored output). ([#1828][github-1828])
* ![Enhancement][badge-enhancement] Documenter now shows a link to the root of the repository in the top navigation bar. The link is determined automatically from the remote repository, unless overridden or disabled via the `repolink` argument of `HTML`. ([#1254][github-1254])
Expand Down Expand Up @@ -1140,6 +1141,8 @@
[github-1908]: https://github.com/JuliaDocs/Documenter.jl/pull/1908
[github-1909]: https://github.com/JuliaDocs/Documenter.jl/pull/1909
[github-1919]: https://github.com/JuliaDocs/Documenter.jl/pull/1919
[github-1931]: https://github.com/JuliaDocs/Documenter.jl/issues/1931
[github-1932]: https://github.com/JuliaDocs/Documenter.jl/pull/1932
[github-1933]: https://github.com/JuliaDocs/Documenter.jl/issues/1933
[github-1935]: https://github.com/JuliaDocs/Documenter.jl/pull/1935
<!-- end of issue link definitions -->
Expand Down
13 changes: 13 additions & 0 deletions assets/latex/documenter.sty
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,16 @@
% and \hyperlink if it doesn't.
\def\hyperlinkref#1#2{\@ifundefined{r@#1}{\hyperlink{#1}{#2}}{\hyperref[#1]{#2}}}
%

% styling of admonitions. tcolorbox is available in the texlive-latex-extra
% package
\usepackage{tcolorbox}
% These colors are taken from documenter-light.css in the HTML assets.
\definecolor{admonition-default}{HTML}{363636}
\definecolor{admonition-danger}{HTML}{da0b00}
\definecolor{admonition-warning}{HTML}{ffdd57}
\definecolor{admonition-note}{HTML}{209cee}
\definecolor{admonition-info}{HTML}{209cee}
\definecolor{admonition-tip}{HTML}{22c35b}
\definecolor{admonition-compat}{HTML}{1db5c9}
%
25 changes: 18 additions & 7 deletions src/Writers/LaTeXWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -466,7 +466,13 @@ function latex(io::Context, node::Node, heading::MarkdownAST.Heading)
io.in_header = true
latex(io, node.children)
io.in_header = false
_println(io, "}\n")
# {sub}pagragraphs need an explicit `\indent` after them
# to ensure the following text is on a new line. Others
if endswith(tag, "paragraph")
_println(io, "}\\indent\n")
else
_println(io, "}\n")
end
end

# Whitelisted lexers.
Expand Down Expand Up @@ -566,13 +572,18 @@ function latex(io::Context, node::Node, ::MarkdownAST.BlockQuote)
end

function latex(io::Context, node::Node, md::MarkdownAST.Admonition)
wrapblock(io, "quote") do
wrapinline(io, "textbf") do
latexesc(io, md.title)
end
_println(io, "\n")
latex(io, node.children)
color = "admonition-default"
if md.category in ("danger", "warning", "note", "info", "tip", "compat")
color = "admonition-$(md.category)"
end
_print(io, "\\begin{tcolorbox}[")
_print(io, "colback=$(color)!5!white,colframe=$(color)!75!black,")
_print(io, "title=\\textbf{")
latexesc(io, md.title)
_println(io, "}]")
latex(io, node.children)
_println(io, "\\end{tcolorbox}")
return
end

function latex(io::Context, node::Node, f::MarkdownAST.FootnoteDefinition)
Expand Down
106 changes: 39 additions & 67 deletions test/examples/references/latex_showcase.tex
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,10 @@ \section{Mathematics}
\begin{quote}
\textbf{Warning}
\begin{tcolorbox}[colback=admonition-warning!5!white,colframe=admonition-warning!75!black,title=\textbf{Warning}]
Similar to LaTeX, using \texttt{\$} and \texttt{\$\$} to escape inline and display equations also works. However, doing so is deprecated and this functionality may be removed in a future release.
\end{quote}
\end{tcolorbox}
\section{Images}
Expand Down Expand Up @@ -180,16 +178,14 @@ \section{Admonitions}
\subparagraph{Note admonition}
\subparagraph{Note admonition}\indent
\label{3427999462323267970}{}
\begin{quote}
\textbf{{\textquotesingle}note{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{{\textquotesingle}note{\textquotesingle} admonition}]
Admonitions look like this. This is a \texttt{!!! note}-type admonition.
Note that admonitions themselves can contain other block-level elements too, such as code blocks. E.g.
Expand All @@ -211,101 +207,89 @@ \subsection{Heading 3}
\subsubsection{Heading 4}
\paragraph{Heading 5}
\paragraph{Heading 5}\indent
\subparagraph{Heading 6}
\subparagraph{Heading 6}\indent
\end{quote}
\end{tcolorbox}
\subparagraph{Info admonition}
\subparagraph{Info admonition}\indent
\label{3520455154602929669}{}
\begin{quote}
\textbf{{\textquotesingle}info{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-info!5!white,colframe=admonition-info!75!black,title=\textbf{{\textquotesingle}info{\textquotesingle} admonition}]
This is a \texttt{!!! info}-type admonition. This is the same as a \texttt{!!! note}-type.
\end{quote}
\end{tcolorbox}
\subparagraph{Tip admonition}
\subparagraph{Tip admonition}\indent
\label{8478099471110135607}{}
\begin{quote}
\textbf{{\textquotesingle}tip{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-tip!5!white,colframe=admonition-tip!75!black,title=\textbf{{\textquotesingle}tip{\textquotesingle} admonition}]
This is a \texttt{!!! tip}-type admonition.
\end{quote}
\end{tcolorbox}
\subparagraph{Warning admonition}
\subparagraph{Warning admonition}\indent
\label{16113256282093947986}{}
\begin{quote}
\textbf{{\textquotesingle}warning{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-warning!5!white,colframe=admonition-warning!75!black,title=\textbf{{\textquotesingle}warning{\textquotesingle} admonition}]
This is a \texttt{!!! warning}-type admonition.
\end{quote}
\end{tcolorbox}
\subparagraph{Danger admonition}
\subparagraph{Danger admonition}\indent
\label{3138459326559650208}{}
\begin{quote}
\textbf{{\textquotesingle}danger{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-danger!5!white,colframe=admonition-danger!75!black,title=\textbf{{\textquotesingle}danger{\textquotesingle} admonition}]
This is a \texttt{!!! danger}-type admonition.
\end{quote}
\end{tcolorbox}
\subparagraph{Compat admonition}
\subparagraph{Compat admonition}\indent
\label{8437579397049066350}{}
\begin{quote}
\textbf{{\textquotesingle}compat{\textquotesingle} admonition}
\begin{tcolorbox}[colback=admonition-compat!5!white,colframe=admonition-compat!75!black,title=\textbf{{\textquotesingle}compat{\textquotesingle} admonition}]
This is a \texttt{!!! compat}-type admonition.
\end{quote}
\end{tcolorbox}
\subparagraph{Unknown admonition class}
\subparagraph{Unknown admonition class}\indent
\label{5611698449794175315}{}
\begin{quote}
\textbf{Unknown admonition class}
\begin{tcolorbox}[colback=admonition-default!5!white,colframe=admonition-default!75!black,title=\textbf{Unknown admonition class}]
Admonition with an unknown admonition class. This is a \texttt{code example}.
\end{quote}
\end{tcolorbox}
\section{Lists}
Expand Down Expand Up @@ -411,9 +395,7 @@ \section{Lists}
\begin{quote}
\textbf{Bulleted lists in admonitions}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{Bulleted lists in admonitions}]
\begin{itemize}
\item Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Expand All @@ -424,12 +406,10 @@ \section{Lists}
\item In non \emph{sodales} eros.
\end{itemize}
\end{quote}
\end{tcolorbox}
\begin{quote}
\textbf{Large lists in admonitions}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{Large lists in admonitions}]
\begin{itemize}
\item Morbi et varius nisl, eu semper orci.
Expand Down Expand Up @@ -461,7 +441,7 @@ \section{Lists}
Fusce nec urna eu orci porta blandit.
\end{itemize}
\end{quote}
\end{tcolorbox}
\begin{quote}
Expand Down Expand Up @@ -585,12 +565,10 @@ \section{Footnotes}
\footnotetext[3]{And a link to another footnote\footnotemark[1].
\begin{quote}
\textbf{Admonition..}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{Admonition..}]
.. in a footnote.
\end{quote}
\end{tcolorbox}
}
Expand Down Expand Up @@ -619,14 +597,14 @@ \subsubsection{Heading level 4}
\label{12782044777122551513}{}
\paragraph{Heading level 5}
\paragraph{Heading level 5}\indent
\label{9543099701887315540}{}
\subparagraph{Heading level 6}
\subparagraph{Heading level 6}\indent
Expand All @@ -637,12 +615,10 @@ \subsubsection{Heading level 4}
\begin{quote}
\textbf{Headings in sidebars}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{Headings in sidebars}]
Level 1 and 2 heading show up in the sidebar, for the current page.
\end{quote}
\end{tcolorbox}
\section{Doctesting example}
Expand Down Expand Up @@ -1083,16 +1059,14 @@ \chapter{Docstrings}
\begin{equation*}
\begin{split}\frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2}\end{split}\end{equation*}
\begin{quote}
\textbf{Long equations in admonitions}
\begin{tcolorbox}[colback=admonition-note!5!white,colframe=admonition-note!75!black,title=\textbf{Long equations in admonitions}]
Inline: \(\frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2}\)
Display equation:
\begin{equation*}
\begin{split}\frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2} + \frac{1+2+3+4+5+6}{\sigma^2}\end{split}\end{equation*}
\end{quote}
\end{tcolorbox}
Long equations in footnotes.[{\textasciicircum}longeq-footnote]
[{\textasciicircum}longeq-footnote]:
Expand Down Expand Up @@ -1140,12 +1114,10 @@ \section{An index of docstrings}
\begin{quote}
\textbf{Missing docstring.}
\begin{tcolorbox}[colback=admonition-warning!5!white,colframe=admonition-warning!75!black,title=\textbf{Missing docstring.}]
Missing docstring for \texttt{this\_docstring\_does\_not\_exist}. Check Documenter{\textquotesingle}s build log for details.
\end{quote}
\end{tcolorbox}
\hypertarget{5308965026370084775}{\texttt{Main.AutoDocs.f}} -- {Function.}
Expand Down
6 changes: 2 additions & 4 deletions test/examples/references/latex_simple.tex
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,10 @@ \section{Escaping: {\textasciitilde}, {\textasciicircum}, {\textbackslash}, {\te



\begin{quote}
\textbf{{\textasciitilde}, {\textasciicircum}, {\textbackslash}, {\textquotesingle}, {\textquotedbl}, \_, \&, \%, {\textbackslash}, \$, \#, \{ and \}.}

\begin{tcolorbox}[colback=admonition-info!5!white,colframe=admonition-info!75!black,title=\textbf{{\textasciitilde}, {\textasciicircum}, {\textbackslash}, {\textquotesingle}, {\textquotedbl}, \_, \&, \%, {\textbackslash}, \$, \#, \{ and \}.}]
{\textasciitilde}, {\textasciicircum}, {\textbackslash}, {\textquotesingle}, {\textquotedbl}, \_, \&, \%, {\textbackslash}, \$, \#, \{ and \}.

\end{quote}
\end{tcolorbox}


\section{Issue 1392}
Expand Down

0 comments on commit 674c02e

Please sign in to comment.