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

Conversation

inkydragon
Copy link
Contributor

@inkydragon inkydragon commented Apr 5, 2022

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
Copy link
Contributor

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 mortenpi added Type: Enhancement Format: LaTeX Related to the LaTeX / PDF output labels Apr 7, 2022
Copy link
Member

@mortenpi mortenpi left a comment

Choose a reason for hiding this comment

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

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

src/Writers/LaTeXWriter.jl Outdated Show resolved Hide resolved
src/Writers/LaTeXWriter.jl Outdated Show resolved Hide resolved
test/run_latex_test.jl Outdated Show resolved Hide resolved
@mortenpi
Copy link
Member

mortenpi commented Apr 7, 2022

@ViralBShah Let's tag after this is merged?

@inkydragon
Copy link
Contributor Author

inkydragon commented Apr 8, 2022

  • 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
Copy link
Contributor Author

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

Temporarily pointing the link to latex/ folder.

@ViralBShah
Copy link
Contributor

Good to merge?


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

CHANGELOG.md Outdated Show resolved Hide resolved
docs/src/man/other-formats.md Outdated Show resolved Hide resolved
docs/src/man/other-formats.md Outdated Show resolved Hide resolved
inkydragon and others added 3 commits April 10, 2022 16:53
Co-authored-by: Morten Piibeleht <morten.piibeleht@gmail.com>
We may add `DocVersion` back later
Copy link
Member

@mortenpi mortenpi left a comment

Choose a reason for hiding this comment

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

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
Copy link
Contributor Author

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.

image

@mortenpi
Copy link
Member

mortenpi commented Apr 11, 2022

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

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
Copy link
Contributor Author

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
Copy link
Member

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.

@mortenpi mortenpi merged commit 401718b into JuliaDocs:master Apr 11, 2022
@inkydragon inkydragon deleted the custom-preamble branch April 12, 2022 02:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Format: LaTeX Related to the LaTeX / PDF output Type: Enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[FR] New way to customize LaTeX preamble
3 participants