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 19 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
4 changes: 4 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] Better spacing between section number and title. ([#1785][github-1785])
* ![Enhancement][badge-enhancement] Allow custom preamble. ([#1788][github-1788])
inkydragon marked this conversation as resolved.
Show resolved Hide resolved

## Version `v0.27.15`

Expand Down Expand Up @@ -996,6 +998,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 \DocVersion }
}
\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 `assert/` folder,
inkydragon marked this conversation as resolved.
Show resolved Hide resolved
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/).
inkydragon marked this conversation as resolved.
Show resolved Hide resolved
You can override the default preamble completely by adding a custom `preamble.tex` to the `assert/` folder.
inkydragon marked this conversation as resolved.
Show resolved Hide resolved

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
62 changes: 17 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,25 @@ 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)}
\\newcommand{\\DocVersion}{$(get(ENV, "TRAVIS_TAG", ""))}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we rarely use TRAVIS anymore, should we just set the \DocVersion variable to VERSION?

Suggested change
\\newcommand{\\DocVersion}{$(get(ENV, "TRAVIS_TAG", ""))}
\\newcommand{\\DocVersion}{ $(VERSION) }

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Travis is definitely gone. @mortenpi ok?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just realized that VERSION refers to the version of julia, but for users of Documenter.jl, it's more like they want the version of their own package.

Maybe this variable should be deprecated or deleted.
If the user needs the version number to be displayed, just append it to the site name.

Copy link
Contributor

@ViralBShah ViralBShah Apr 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was just thinking the same thing - I don't recollect what TRAVIS_TAG refers to.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TRAVIS_TAG: If the current build is for a git tag, this variable is set to the tag’s name, otherwise it is empty ("").
Environment Variables - Travis CI

And

- `TRAVIS_TAG`: if set, a tagged version deployment is performed instead; the value
must be a valid version number (i.e. match `Base.VERSION_REGEX`). The documentation for
a package version tag gets deployed to a directory named after the version number in
`TRAVIS_TAG` instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this would just try to determine the package version number automatically, but only works if it's being used on Travis (or if the user sets the environment variable themselves; e.g. it used to work for Documenter). However, I don't think it's actually good that it's quietly relying on the enviroment variable.

I would suggest adding another version variable to the LaTeX object. To make this non-breaking and non-behavior-changing, it can still just default to get(ENV, "TRAVIS_TAG", ""), but I think it should be documented that this default is deprecated. On the Julia side, we can then populate this new option so that the resulting PDFs would actually contain a version number.

\\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
\DocVersion
\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 \DocVersion }
}
\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