[TeX] Allow custom preamble (#1788)

.github/workflows/CI.yml

@@ -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"

CHANGELOG.md

@@ -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`
 
@@ -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
@@ -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

assets/latex/preamble.tex

@@ -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

docs/src/man/other-formats.md

@@ -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)

src/Writers/LaTeXWriter.jl

@@ -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)
 
@@ -214,54 +215,27 @@ 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)}
+        \\newcommand{\\JuliaVersion}{$(VERSION)}
+        
+        % ---- Insert preamble
+        \\input{preamble.tex}
         """
+    # output preamble
     _println(io, preamble)
 end
 

test/examples/make.jl

@@ -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

test/examples/src.cover_page/assets/preamble.tex

@@ -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

test/examples/src.cover_page/assets/titlepage.tex

@@ -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  Built by Julia \JuliaVersion }
+\vspace*{3cm}\par\noindent
+
+\textbf{  \DocAuthors  }
+\vfill
+
+%% ---- logo
+\includegraphics[width=0.4\textwidth]{example-image}
+\\[1.5cm]
+
+\Large
+\deprecatedEnvTravisTag
+\today
+
+\end{center}
+\end{titlingpage}

test/examples/src.cover_page/index.md

@@ -0,0 +1,3 @@
+# Test Case: Customized Cover Page
+
+![cover](./assets/cover.png)

test/examples/src.toc_style/assets/preamble.tex

@@ -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

test/examples/src.toc_style/index.md

@@ -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)

test/examples/tests_latex.jl

@@ -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
@@ -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