Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TeX] Allow custom preamble #1788

Merged
merged 24 commits into from
Apr 11, 2022
Merged
Show file tree
Hide file tree
Changes from 22 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
31be46a
[TeX] Allow custom preamble
inkydragon Apr 5, 2022
a8fd795
[TeX] Keep default preamble untouched
inkydragon Apr 5, 2022
9c78614
[TeX] fix typo
inkydragon Apr 6, 2022
e3932d8
[TeX] add a cover_page example
inkydragon Apr 6, 2022
26b3f22
[TeX] add a toc-style example
inkydragon Apr 6, 2022
ea0f13c
[test] Add new test to runtest
inkydragon Apr 6, 2022
6cbc706
[TeX] use snake case filename
inkydragon Apr 6, 2022
9c6a063
[TeX] move to dir
inkydragon Apr 6, 2022
7462011
[test] only build PDF on ubuntu
inkydragon Apr 6, 2022
7bf8de9
[test/tex] rename testset
inkydragon Apr 6, 2022
015a68a
[repo] Add CHANGELOG entry
inkydragon Apr 8, 2022
adf8259
[TeX] moving preamble into separate file
inkydragon Apr 8, 2022
b2060aa
[TeX] rename `preamble_tex_file` to `custom_preamble_file`
inkydragon Apr 8, 2022
947997f
[test] move TeX examples to `test/examples`
inkydragon Apr 8, 2022
f204fa0
[test] Use same sitename
inkydragon Apr 8, 2022
3a256de
[test] open all test
inkydragon Apr 8, 2022
430c06a
[ci] upload PDF artifact
inkydragon Apr 8, 2022
585c9c9
[doc] add doc for Custom LaTeX style
inkydragon Apr 8, 2022
e0a2c6f
[doc] Temporarily pointing the link to the folder
inkydragon Apr 8, 2022
5ced822
Apply suggestions from code review ( mortenpi )
inkydragon Apr 10, 2022
c488b9f
[repo] Add link in CHANGELOG
inkydragon Apr 10, 2022
465b3d5
[tex] rename `DocVersion` to `deprecatedEnvTravisTag`
inkydragon Apr 10, 2022
777f41a
[tex] Add new tex variable: `\JuliaVersion`
inkydragon Apr 11, 2022
028d103
[test] Use new tex variable in test
inkydragon Apr 11, 2022
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/CI.yml
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ jobs:
- uses: codecov/codecov-action@v1
with:
file: lcov.info
- uses: actions/upload-artifact@v3
with:
name: PDFs
path: test/examples/builds/*/*.pdf

themes:
name: "CSS for HTML themes"
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

* ![Enhancement][badge-enhancement] Update CSS source file for JuliaMono, so that all font variations are included (not just `JuliaMono Regular`) and that the latest version (0.039 -> 0.044) of the font would be used. ([#1780][github-1780], [#1784][github-1784])
* ![Bugfix][badge-bugfix] Fix `strict` mode to properly print errors, not just a warnings. ([#1756][github-1756], [#1776][github-1776])
* ![Enhancement][badge-enhancement] The table of contents in the generated PDFs have more space between section numbers and titles to avoid them overlapping. ([#1785][github-1785])
* ![Enhancement][badge-enhancement] The preamble of the LaTeX source of the PDF build can now be customized by the user. ([#1746][github-1746], [#1788][github-1788])

## Version `v0.27.15`

Expand Down Expand Up @@ -978,6 +980,7 @@
[github-1716]: https://github.com/JuliaDocs/Documenter.jl/pull/1716
[github-1727]: https://github.com/JuliaDocs/Documenter.jl/pull/1727
[github-1743]: https://github.com/JuliaDocs/Documenter.jl/pull/1743
[github-1746]: https://github.com/JuliaDocs/Documenter.jl/issues/1746
[github-1748]: https://github.com/JuliaDocs/Documenter.jl/pull/1748
[github-1750]: https://github.com/JuliaDocs/Documenter.jl/pull/1750
[github-1751]: https://github.com/JuliaDocs/Documenter.jl/pull/1751
Expand All @@ -996,6 +999,8 @@
[github-1776]: https://github.com/JuliaDocs/Documenter.jl/pull/1776
[github-1780]: https://github.com/JuliaDocs/Documenter.jl/issues/1780
[github-1784]: https://github.com/JuliaDocs/Documenter.jl/pull/1784
[github-1785]: https://github.com/JuliaDocs/Documenter.jl/pull/1785
[github-1788]: https://github.com/JuliaDocs/Documenter.jl/pull/1788
<!-- end of issue link definitions -->

[julia-38079]: https://github.com/JuliaLang/julia/issues/38079
Expand Down
46 changes: 46 additions & 0 deletions assets/latex/preamble.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
%% Default preamble BEGIN
\documentclass[oneside]{memoir}

\usepackage{./documenter}
\usepackage{./custom}

%% Title Page
\title{
{\HUGE \DocMainTitle }\\
{\Large \deprecatedEnvTravisTag }
}
\author{ \DocAuthors }

%% TOC settings
% -- TOC depth
% value: [part, chapter, section, subsection,
% subsubsection, paragraph, subparagraph]
\settocdepth{section} % show "part+chapter+section" in TOC
% -- TOC spacing
% ref: https://tex.stackexchange.com/questions/60317/toc-spacing-in-memoir
% doc: memoir/memman.pdf
% - Figure 9.2: Layout of a ToC
% - Table 9.3: Value of K in macros for styling entries
\makeatletter
% {part} to {chaper}
\setlength{\cftbeforepartskip}{1.5em \@plus \p@}
% {chaper} to {chaper}
\setlength{\cftbeforechapterskip}{0.0em \@plus \p@}
% Chapter num to chapter title spacing (Figure 9.2@memman)
\setlength{\cftchapternumwidth}{2.5em \@plus \p@}
% indent before section number
\setlength{\cftsectionindent}{2.5em \@plus \p@}
% Section num to section title spacing (Figure 9.2@memman)
\setlength{\cftsectionnumwidth}{4.0em \@plus \p@}
\makeatother

%% Main document begin
\begin{document}

\frontmatter
\maketitle
\clearpage
\tableofcontents

\mainmatter
%% preamble END
28 changes: 28 additions & 0 deletions docs/src/man/other-formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,34 @@ makedocs(
)
```

## [Custom LaTeX style](@id custom-latex)

### Load custom packages

We have loaded many common packages in LaTeX,
such as `fontspec`, `amsmath`, `listings`, `minted`, `tabulary`, `graphicx`,
and more detailed configurations can be found in [`documenter.sty`](https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/latex/documenter.sty).

Users can load more custom packages by adding a `custom.sty` to the `assets/` folder,
and the custom style (`custom.sty`) will be loaded after the default style (`documenter.sty`).

### Custom preamble

If you wish to fully customize the package loading, you need to write a custom preamble.

The default preamble is currently defined in [`preamble.tex`](https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/latex/preamble.tex).
You can override the default preamble completely by adding a custom `preamble.tex` to the `assets/` folder.

There are two examples of custom preambles:
- Custom [cover page][cover_page_src], ([make.jl][cover_page_makejl])
- Customizing [the TOC display][toc_display_src], ([make.jl][toc_display_makejl])

[cover_page_src]: https://github.com/JuliaDocs/Documenter.jl/tree/master/test/examples/src.cover_page
[toc_display_src]: https://github.com/JuliaDocs/Documenter.jl/tree/master/test/examples/src.toc_style
[cover_page_makejl]: https://github.com/JuliaDocs/Documenter.jl/blob/master/test/examples/make.jl#L492-L502
[toc_display_makejl]: https://github.com/JuliaDocs/Documenter.jl/blob/master/test/examples/make.jl#L511-L521


## Markdown & MkDocs

Markdown output requires the [`DocumenterMarkdown`](https://github.com/JuliaDocs/DocumenterMarkdown.jl)
Expand Down
63 changes: 18 additions & 45 deletions src/Writers/LaTeXWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ _println(c::Context, args...) = Base.println(c.io, args...)


const STYLE = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "documenter.sty")
const DEFAULT_PREAMBLE_PATH = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "preamble.tex")

hastex() = (try; success(`latexmk -version`); catch; false; end)

Expand Down Expand Up @@ -214,54 +215,26 @@ end
function writeheader(io::IO, doc::Documents.Document)
custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty")
isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty")

custom_preamble_file = joinpath(doc.user.root, doc.user.source, "assets", "preamble.tex")
if isfile(custom_preamble_file)
# copy custom preamble.
cp(custom_preamble_file, "preamble.tex"; force = true)
else # no custom preamble.tex, use default.
cp(DEFAULT_PREAMBLE_PATH, "preamble.tex"; force = true)
end
preamble =
"""
\\documentclass[oneside]{memoir}

\\usepackage{./documenter}
\\usepackage{./custom}

%% Title Page
\\title{
{\\HUGE $(doc.user.sitename)}\\\\
{\\Large $(get(ENV, "TRAVIS_TAG", ""))}
}
\\author{$(doc.user.authors)}

%% TOC settings
% -- TOC depth
% value: [part, chapter, section, subsection,
% subsubsection, paragraph, subparagraph]
\\settocdepth{section} % show "part+chapter+section" in TOC
% -- TOC spacing
% ref: https://tex.stackexchange.com/questions/60317/toc-spacing-in-memoir
% doc: memoir/memman.pdf
% - Figure 9.2: Layout of a ToC
% - Table 9.3: Value of K in macros for styling entries
\\makeatletter
% {part} to {chaper}
\\setlength{\\cftbeforepartskip}{1.5em \\@plus \\p@}
% {chaper} to {chaper}
\\setlength{\\cftbeforechapterskip}{0.0em \\@plus \\p@}
% Chapter num to chapter title spacing (Figure 9.2@memman)
\\setlength{\\cftchapternumwidth}{2.5em \\@plus \\p@}
% indent before section number
\\setlength{\\cftsectionindent}{2.5em \\@plus \\p@}
% Section num to section title spacing (Figure 9.2@memman)
\\setlength{\\cftsectionnumwidth}{4.0em \\@plus \\p@}
\\makeatother

%% Main document begin
\\begin{document}

\\frontmatter
\\maketitle
\\clearpage
\\tableofcontents

\\mainmatter

% Useful variables
\\newcommand{\\DocMainTitle}{$(doc.user.sitename)}
% Warning: The default value of \\deprecatedEnvTravisTag is deprecated.
\\newcommand{\\deprecatedEnvTravisTag}{$(get(ENV, "TRAVIS_TAG", ""))}
\\newcommand{\\DocAuthors}{$(doc.user.authors)}

% ---- Insert preamble
\\input{preamble.tex}
"""
# output preamble
_println(io, preamble)
end

Expand Down
38 changes: 38 additions & 0 deletions test/examples/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -486,3 +486,41 @@ else
@debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
nothing
end

examples_latex_cover_page = if "latex_cover_page" in EXAMPLE_BUILDS
@info("Building mock package docs: LaTeXWriter/latex_cover_page")
@quietly makedocs(
format = Documenter.Writers.LaTeXWriter.LaTeX(platform = "docker"),
sitename = "Documenter LaTeX",
root = examples_root,
build = "builds/latex_cover_page",
source = "src.cover_page",
pages = ["Home" => "index.md"],
authors = "The Julia Project",
doctest = false,
debug = true,
)
else
@info "Skipping build: LaTeXWriter/latex_cover_page"
@debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
nothing
end

examples_latex_toc_style = if "latex_toc_style" in EXAMPLE_BUILDS
@info("Building mock package docs: LaTeXWriter/latex_toc_style")
@quietly makedocs(
format = Documenter.Writers.LaTeXWriter.LaTeX(platform = "docker"),
sitename = "Documenter LaTeX",
root = examples_root,
build = "builds/latex_toc_style",
source = "src.toc_style",
pages = ["Part-I" => "index.md"],
authors = "The Julia Project",
doctest = false,
debug = true,
)
else
@info "Skipping build: LaTeXWriter/latex_toc_style"
@debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
nothing
end
Binary file added test/examples/src.cover_page/assets/cover.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions test/examples/src.cover_page/assets/preamble.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
\documentclass[oneside]{memoir}

\usepackage{./documenter}
\usepackage{./custom}

%% Main document begin
\begin{document}

\input{assets/titlepage.tex}

\frontmatter
% \maketitle
\clearpage
\tableofcontents

\mainmatter
26 changes: 26 additions & 0 deletions test/examples/src.cover_page/assets/titlepage.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
% ref: P65 - http://mirrors.ctan.org/macros/latex/contrib/memoir/memman.pdf
\begin{titlingpage}
\begin{center}
\vspace*{2cm}\noindent

%% ---- Main title
\Huge \textbf{ \DocMainTitle }
\\[0.6cm]

%% ---- Subtitle
{\LARGE Subtitle }
\vspace*{3cm}\par\noindent

\textbf{ \DocAuthors }
\vfill

%% ---- logo
\includegraphics[width=0.4\textwidth]{example-image}
\\[1.5cm]

\Large
\deprecatedEnvTravisTag
\today

\end{center}
\end{titlingpage}
3 changes: 3 additions & 0 deletions test/examples/src.cover_page/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Test Case: Customized Cover Page

![cover](./assets/cover.png)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
25 changes: 25 additions & 0 deletions test/examples/src.toc_style/assets/preamble.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
\documentclass[oneside]{memoir}
\usepackage{./documenter}
\usepackage{./custom}

%% Title Page
\title{
{\HUGE \DocMainTitle }\\
{\Large \deprecatedEnvTravisTag }
}
\author{ \DocAuthors }

%% TOC settings
% -- TOC depth
% value: [part, chapter, section, subsection,
% subsubsection, paragraph, subparagraph]
\settocdepth{chapter} % show "part+chapter" in TOC


%% Main document begin
\begin{document}
\frontmatter
\maketitle
\clearpage
\tableofcontents
\mainmatter
28 changes: 28 additions & 0 deletions test/examples/src.toc_style/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# LaTeX backend test case: LaTeX TOC style


With the default settings of `Documenter.jl`, the section name will be displayed in the TOC.

```tex
%% TOC settings
% -- TOC depth
% value: [part, chapter, section, subsection,
% subsubsection, paragraph, subparagraph]
\settocdepth{section} % show "part+chapter+section" in TOC
```

You can modify settings that related to the TOC format by add customized `preamble.tex`.

## Only show part and chapter in TOC

```tex
\settocdepth{part} % show "part+chapter" in TOC
```

## Default style vs. custom style

Left side: default style, show "part+chapter+section" in TOC.

Right side: custom style, show "part+chapter" in TOC.

![default vs. customized](./assets/default-customized.png)
19 changes: 18 additions & 1 deletion test/examples/tests_latex.jl
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ using Test

# DOCUMENTER_TEST_EXAMPLES can be used to control which builds are performed in
# make.jl, and we need to set it to the relevant LaTeX builds.
ENV["DOCUMENTER_TEST_EXAMPLES"] = "latex latex_simple latex_texonly"
ENV["DOCUMENTER_TEST_EXAMPLES"] =
"latex latex_simple latex_texonly latex_cover_page latex_toc_style"

# When the file is run separately we need to include make.jl which actually builds
# the docs and defines a few modules that are referred to in the docs. The make.jl
Expand Down Expand Up @@ -49,4 +50,20 @@ end
@test joinpath(build_dir, "documenter.sty") |> isfile
end
end

@testset "PDF/LaTeX: Custom Cover Page" begin
doc = Main.examples_latex_cover_page
@test isa(doc, Documenter.Documents.Document)
let build_dir = joinpath(examples_root, "builds", "latex_cover_page")
@test joinpath(build_dir, "DocumenterLaTeX$(tagsuffix).pdf") |> isfile
end
end

@testset "PDF/LaTeX: Custom TOC Style" begin
doc = Main.examples_latex_toc_style
@test isa(doc, Documenter.Documents.Document)
let build_dir = joinpath(examples_root, "builds", "latex_toc_style")
@test joinpath(build_dir, "DocumenterLaTeX$(tagsuffix).pdf") |> isfile
end
end
end