Deploying documentation with Documenter (automatically with each new push to the repo)

I made a small package as a way of “practicing” all of the good software practices (CI, unit tests, coverage testing, etc). Here it is: GitHub - glwhart/MinkowskiReduction.jl: Lattice reduction in three dimensions

I used a template and PkgTemplate. I finally got coverage testing and travis and all that working. When I make a change and push to the repo, all the tests run, the badges are updated, etc.

But I can’t get the documentation to show up on github. (You’ll notice that the docs badge is a broken link…Dev)

In fact, the documentation is not being deployed to gh-pages branch on the package’s repo. When make.jl runs, the documentation is created—I can see it a build directory inside docs. But the contents don’t automatically get pushed to github. I can’t figure out why. I believe I followed all the directions given in the Documenter.jl docs (like adding keys, etc.), but I’m still stuck.

When I run julia make.jl in the docs. It looks like this:

➜  dev/MinkowskiReduction/docs git:(main) ✗ julia make.jl 
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/bFHi4/src/deployconfig.jl:75

Not sure that Warning is relevant…but ‘skipping deployment’ sounds like my problem. Not sure why the building environment is not known. To me it’s obviously the docs/build folder…

Any ideas what I failed to do in my setup? Or what maybe I did wrong?

Is there some log file or something I should be looking at to debug this? Sorry for the newbie questions. I’m still figuring out all the package stuff.

4 Likes

I have struggled a bit with that, and annotated my workflow here: Publish Docs · JuliaNotes.jl

11 Likes

Thank you @lmiq. I looked through your notes carefully and I did learn a couple of things.

However, I’m still not getting my docs to show up at Home · MinkowskiReduction.jl

I have two questions for the community at large.

  1. If everything is working, should I see html files in my gh-pages branch on my github repo?
  2. If I run julia make.jl on my local copy of the repo (rather than having travis-ci do it, or github actions) should it still work? Should it deploy my docs to github?

Yes, and that seems to be ok in your repo.

That will create a local copy of the page. You can see and edit it locally. I use a simple script that launches a python-based local server (http.server) for that:

# file:  webserver.sh
previous=`ps aux | grep python3 |grep http.server| awk '{print $2}'`
if [[ $previous > "" ]];then 
  kill -9 $previous
fi
python3 -m http.server --bind localhost

If you run webserver.sh from the build directory created with make.jl you will be able to see your page at http://127.0.0.1:8000/.

But, answering your question, that does not publish your docs.

Finally, I can’t see anything wrong with your docs. Did you do, in github:

Settings -> GitHub Pages -> choose gh-pages (/root)

I am not sure if that is not done automatically, but I always did that.

1 Like

Oh! Almost there! I hadn’t changed the settings in the repo:
Settings -> GitHub Pages -> choose gh-pages (/root)

Now with that change, the documentation is visible at:
https://glwhart.github.io/MinkowskiReduction.jl/

but my badges created by the PkgTemplate package point to dev and stable branches so those links are still broken…(I guess I’ll live without different branches of the docs for now).

But I’m really excited to have the documentation showing up finally. Thank you!

I can’t get the html pages to build on my project WaterLily.jl and I’m general confused about the gh-pages branch. Why is this needed and what should be different on this branch compared to master? Every time I make a change on master, will I have to merge that change into gh-pages in order to refresh the documents (once I actually get them working)?

The gh-pages banch should not contain the code contained in the main branch. It is started as an empty branch (either manually, or automatically when the documentation is deployed for the first time), and when the documentation is deployed, the built docs are stored there. For example:

Main branch: https://github.com/m3g/SPGBox.jl

gh-pages branch: GitHub - m3g/SPGBox.jl at gh-pages

Progress!

  • Github actions automatically made gh-pages!
  • I see the index.html file in the dev folder
  • The website is still giving a 404.

How does github know which index.html to use? I noticed your example has 20 folders in it…

Now probably you have to deploy again the stable version, with this: Publish Docs · JuliaNotes.jl

(bottom of the page)

But next time you create a tag, probably everything will work.

ps: The site will be called https://weymouth.github.io/WaterLily.jl/stable

and this: WaterLily · WaterLily.jl

is working already.

2 Likes

Oh, cool. That’ll work!

Hey everyone! I first apologise to revive this topic but I’ve been following @Imiq guide Publish Docs · JuliaNotes.jl for the keys generation etc but still, my (manually created) gh-pages branch remains empty after the deployment action… Here is the package GitHub - AntoineRestivo/BosonSampling.jl: Boson sampling tools for Julia. I was wondering wether I need to put the value of the (public) key somewhere in the workflow files or not.

Thanks in advance!

1 Like

My understanding of that is only empirical, but creating an empty branch is different from creating a branch with nothing in it. I can only recommend deleting that branch and starting over, creating the empty branch from the GitHub site.

Thanks for your prompt reply! Even by creating gh-pages properly as an orphan branch, our documentation still comes from the readme file only.

1 Like

For completeness, my problem is resolved thanks to a ci.yml file. Your previous answers were really helpful!

1 Like

Hi, I followed the instructions from this “Publish Docs · JuliaNotes.jl” topic, but I didn’t manage to deploy GitHub Pages. The repository is GitHub - shayandavoodii/MFF and the error of CI workflow is as follows:

CI error

The error is available here: removed · shayandavoodii/MFF@ed7694d · GitHub

Run julia --project=docs -e '
  Installing known registries into `~/.julia`
    Updating registry at `~/.julia/registries/General.toml`
   Resolving package versions...
ERROR: expected package `MFF [99a43ef4]` to be registered
Stacktrace:
  [1] pkgerror(msg::String)
    @ Pkg.Types /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Types.jl:67
  [2] check_registered
    @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1190 [inlined]
  [3] targeted_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
    @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1252
  [4] tiered_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, julia_version::VersionNumber)
    @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1225
  [5] _resolve(io::Base.PipeEndpoint, env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
    @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1260
  [6] add(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}, new_git::Set{Base.UUID}; preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform)
    @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1276
  [7] add(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}; preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform, kwargs::Base.Pairs{Symbol, Base.PipeEndpoint, Tuple{Symbol}, NamedTuple{(:io,), Tuple{Base.PipeEndpoint}}})
    @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:275
  [8] add(pkgs::Vector{Pkg.Types.PackageSpec}; io::Base.PipeEndpoint, kwargs::Base.Pairs{Symbol, Union{}, Tuple{}, NamedTuple{(), Tuple{}}})
    @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:156
  [9] add(pkgs::Vector{Pkg.Types.PackageSpec})
    @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:145
 [10] #add#27
    @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:144 [inlined]
 [11] add
    @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:144 [inlined]
 [12] #add#26
    @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:143 [inlined]
 [13] add(pkg::String)
    @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:143
 [14] top-level scope
    @ none:2
Error: Process completed with exit code 1.

I get “file not found” in https://shayandavoodii.github.io/MFF/.

Note that MFF is not intended to be registered.

I think your gh-pages branch is not an originally empty branch to be populated automatically by the CI run. That may be a problem.

So, should I remove the branch, and initialize a new empty branch and paste the contents in it?

As far as I understand, yes, you need to remove the branch and create an empty one. But you don’t need to do anything else, the content will be created automatically by the CI script once you tag a new version. (this part: Publish Docs · JuliaNotes.jl)

Do you mean CI workflow reads the content of the master branch and automatically handles creating gh-branch and deployment?

I removed the gh-pages branch and followed the commands that you referred to. So, the new fresh gh-pages got created. Afterward, I published a new release, but the error remained as before.

Also, the gh-pages branch is empty still.