[TeX] Allow custom preamble

[inkydragon]

Close #1746.

• There are no changes to the default preamble.
• You can add a custom preamble.tex file to override the default preamble.
• example: Customized TOC style
• example: Cover page

Ready for review.

[ViralBShah]

For now, we are ok with the current TOC depth at section level, and don't necessarily want to be able to keep it at chapter level.

[mortenpi]

LGTM, just a couple of organizational comments, and a few last things:

• Could use a CHANGELOG entry for this, including a reference to [LaTexWriter] Better spacing between section number and title #1785, since that PR didn't add a CHANGELOG entry.
• It would also be nice to have a note in the documentation about the possibility to override the preamble.

[mortenpi]

@ViralBShah Let's tag after this is merged?

[inkydragon]

• Please feel free to touch up and rewrite these newly added documents and ChangeLog.
  • "Could use a CHANGELOG entry for this."
  • "have a note in the doc"
• "Add assets/latex/preamble.tex"
• "use this (\Doc* variables) for the native preamble"
• "move new test to test/examples"

---

• Upoad output PDFs

[inkydragon]

Linkcheck failed because the new link is only valid when this pr is merged.

• https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/latex/preamble.tex

Temporarily pointing the link to latex/ folder.

[ViralBShah]

Good to merge?

[inkydragon]

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

[ViralBShah]

Travis is definitely gone. @mortenpi ok?

[inkydragon]

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.

[ViralBShah]

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

[inkydragon]

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

Documenter.jl/src/deployconfig.jl

Lines 136 to 139 in cd49b07

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

[mortenpi]

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.

[mortenpi]

LGTM as is, but are you sure we don't want to make the version number configurable? We could then always pass version = VERSION in Julia's doc/make.jl so that at least the Julia PDF always has a version number.

[inkydragon]

but are you sure we don't want to make the version number configurable?

We certainly want a configurable version number.
But I haven't figured out how to customize the version number, add a new environment variable or add a new keyword parameter (for makedocs).

Perhaps we can start by adding a julia version number variable.

[mortenpi]

I would just add the version number option to the LaTeX struct:

Documenter.jl/src/Writers/LaTeXWriter.jl

Lines 43 to 49 in cd49b07

	struct LaTeX <: Documenter.Writer
	platform::String
	function LaTeX(; platform = "native")
	platform ∈ ("native", "docker", "none") || throw(ArgumentError("unknown platform: $platform"))
	return new(platform)
	end
	end

You can then set it by e.g. makedocs(..., format = LaTeX(version = VERSION)).

In principle, it wouldn't be a bad idea to have it be an argument to makedocs, so that other writers (i.e. HTML) could also use it. But that would (a) require using it in the HTML build, and (b) a general rethink how version numbers are handled (which is mostly done in deploydocs right now). So, in the future, perhaps, but I wouldn't complicate this PR with it.

[inkydragon]

So, in the future, perhaps, but I wouldn't complicate this PR with it.

Yes, maybe open a new issue to track this.

This PR is ready for merge.

[mortenpi]

Awesome, thanks @inkydragon!

Also, I just noticed the uploading of the PDF artifacts --- that's super handy. We should look into managing preview builds with this too.