Test documentation on latest Julia release

[omus]

I just noticed that PkgTemplates wasn't included in the docs/Project.toml which is required in Julia 1.3.

[christopher-dG]

Is there somewhere other than the Documenter docs that I can get info on this change? Just want to make sure I can see the whole picture because if there are new best practices, then the Documenter plugin should probably be updated too.

[omus]

This is actually a Julia 1.3 requirement rather than a Documenter requirement. I'm not sure the PR it's from but it would be from the Pkg.jl repo.

$ git checkout ab9949a
$ julia-1.3 --project=docs/ docs/make.jl
ERROR: LoadError: ArgumentError: Package PkgTemplates not found in current path:
- Run `import Pkg; Pkg.add("PkgTemplates")` to install the PkgTemplates package.

Stacktrace:
 [1] require(::Module, ::Symbol) at ./loading.jl:887
 [2] include at ./boot.jl:328 [inlined]
 [3] include_relative(::Module, ::String) at ./loading.jl:1105
 [4] include(::Module, ::String) at ./Base.jl:31
 [5] exec_options(::Base.JLOptions) at ./client.jl:287
 [6] _start() at ./client.jl:460
in expression starting at /Users/omus/.julia/dev/PkgTemplates/docs/make.jl:2

[codecov]

Codecov Report

Merging #139 into master will not change coverage by %.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #139   +/-   ##
=======================================
  Coverage   93.61%   93.61%           
=======================================
  Files          17       17           
  Lines         329      329           
=======================================
  Hits          308      308           
  Misses         21       21           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ba14f89...d9d126b. Read the comment docs.

[omus]

Rebased changes.

[christopher-dG]

Seems good to me. Is this (adding the package to its own docs/{Project,Manifest}.toml) what we should be doing for generated packages from now on too? Right now the documentation is built on 1.0 so it's not necessary AFAIK. Does the docs/Manifest.toml need to be updated whenever a new dependency is added to the package being documented?

[nickrobinson251]

Is this (adding the package to its own docs/{Project,Manifest}.toml) what we should be doing for generated packages from now on too?

Yes; docs/ should have docs/Project.toml including the Package itself as a dependency to be able to generate the API docs. In particular, the default docs/make.jl file depends on the Package, so needs to be an explicit docs dependency.

the Documenter plugin should probably be updated too.

Yep. Using the Documenter plugin, then running julia --project=docs/ docs/make.jl gives

ERROR: LoadError: ArgumentError: Package Foo not found in current path:
- Run `import Pkg; Pkg.add("Foo")` to install the Foo package.

(I don't think this ever worked)

[omus]

Right now the documentation is built on 1.0 so it's not necessary AFAIK. Does the docs/Manifest.toml need to be updated whenever a new dependency is added to the package being documented?

Unfortunately using a docs/Manifest.toml does mean it needs to be periodically updated. I think the CompatHelper GitHub action may assist with this. I think we can leave the default as having the CI do Pkg.develop(PackageSpec(path=pwd())) for documentation. The main advantage of having a docs/Manifest.toml is it ensures that when building documentation locally you're using the local project and not the latest release.

[christopher-dG]

Alright I'll merge this and open a new issue to mention that we should probably update the Documenter plugin.