Fix stable documentation builds

[moustachio-belvedere]

Automatic code coverage updating has now been adding to the travis config file but it's not yet testing on all operating systems as a result of moving the testing phase into its own 'job'.

Best to clean up the config file, possibly by moving documentation build out to github actions instead of travis.

Sorting this will make progress to resolving https://github.com/JuliaRheology/RHEOS.jl/issues/58 for good.

I'll try get it done this week.

[moustachio-belvedere]

moving docs build to a github action to keep it separate and so it can be triggered upon pushing of tags

update: github action keeps triggering errors, the standard example in Documenter.jl docs is not sufficient as we are running the jupyter notebook -> markdown extension which requires python packages and more complex build script.

[moustachio-belvedere]

Make.jl is running local builds fine on my Windows machine, but still running into a directory error during the Github action despite many attempts to fix. Will try and look at this again tomorrow, had to work on some other things today.

[moustachio-belvedere]

Strange, this is working fine on my Windows 7 machine, and Ale tested on her Ubuntu 18.04 computer. Both local builds worked fine without issue. I'm wondering if it is a strange interaction with this bug:

https://github.com/jupyter/nbconvert/issues/293

The key error we're getting during the github action is the following:

ERROR: LoadError: IOError: could not spawn "jupyter nbconvert examples/burgers.ipynb --to markdown --template docs/documenter.tpl --output-dir docs/src-staging": no such file or directory (ENOENT)

(I replaced backticks in original error message with speech marks to avoid formatting change.)

But jupyter nbconvert on it's own works fine and brings up the help docs as it does locally on my computer. Just tested absolute directories/paths as suggested in that issue but the problem persists. I tested if the working directory is correct before the jupter nbconvert call and it does seem to be.

I've tested remotely Github actions on both Ubuntu 16.04 and 18.04. Error is the same on both.

Edit: I think this is the user who gave us the original inspiration, I'm trying to understand how their repository is currently configured but it now uses a much more complicated build system that also involves docker

https://github.com/marius311/CMBLensing.jl/blob/master/docs/make.jl

[moustachio-belvedere]

I have a possible fix to this but has involved not using Github actions and going back to Travis CI, but I need to test it. I can delete the test tag afterwards but just in case something goes wrong I'm temporarily renaming the 0.9.3 milestone to 0.9.4 so it doesn't clash with the 0.9.3 test tag. If it works on a push from us, hopefully it will work on a push from tagbot. If it doesn't we can tag manually for stable doc versions or figure out another way round the problem.

[moustachio-belvedere]

Travis is now triggering documentation builds on tag pushing which is good, but for some reason a documentation build triggered by a tag push is giving a mysterious error as shown at the end of https://travis-ci.org/github/JuliaRheology/RHEOS.jl/jobs/692352295

┌ Error: Failed to push:
│   exception =
│    ArgumentError: link "v0.9" => "v0.9.3" incompatible with link "v0.9.0" => "v0.9".

Cleaning up test tags for now

edit: Further discussion at https://github.com/JuliaDocs/Documenter.jl/issues/1330

[moustachio-belvedere]

Note for discussion later today, to simplify this build process in future, I suggest we consider switching from pure Jupyter notebooks to using .jl files and combine with this package Literate.jl (https://github.com/fredrikekre/Literate.jl) so that both markdown and notebooks can be generated from them. This will likely avoid many difficult issues in the future when things (inevitably) change with recommended documentation build procedures etc.

[moustachio-belvedere]

https://www.youtube.com/watch?v=Tfp1WEdYfqk

There's the Juliacon talk on it, it looks really cool and is perfect for our needs because we can also add some unit tests to the doc source scripts so we'll be immediately notified if they get out of date.

[akabla]

The build is working according to Travis, but I'm not sure it is producing the right doc for the latest master under the "dev" link. I can't really my head around what it is supposed to do.

[moustachio-belvedere]

Investigating this now... Sometimes it does take a bit of time for the docs to be updated, even after a succesful build but that may not be the issue as I got a different docs failed to build notification this morning.

Edit: for reference, this was the email I got, I can't find the notification on Github

The page build failed for the gh-pages branch with the following error:

Page build failed. For more information, see https://help.github.com/en/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#troubleshooting-build-errors.

For information on troubleshooting Jekyll see:

https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request on the Contact GitHub page at https://support.github.com/contact?repo_id=120333578&page_build_id=183345248

Doesn't provide much insight into what went wrong though...

[akabla]

I agree. I'm wondering if it wouldn't be easier to generate the doc locally and push it to the repo. Not as nice as an automated process, but we'd only need to do that around the time of the production of a new release, or when working on it explicitly in a branch. In this case, running it locally would be actually very helpful (as for the unit tests). The make.jl file is probably all we need I guess? I'm not soo sure how the deployment works.

On a different but related note, nbconvert can extract code from the notebooks, so we may be able to run tests on them too as part of the doc building process.

[moustachio-belvedere]

Not sure what went wrong but started from a clean gh-pages branch (apart from index.html which I kept as it is just a redirect file) and re-built, it works from master/dev now. The moduli functions are now listed in the API section.

On a different but related note, nbconvert can extract code from the notebooks, so we may be able to run tests on them too as part of the doc building process.

I think that might be fiddly because, as far as I understand, we would have to add a Travis step to all test runs that makes sure the correct versions of python, jupyter and nbconvert are installed, then convert to code before we start running the test script. It's doable, but given that those python dependencies are pain point (versions must be correct, nbconvert syntax has varied enough over different versions to make it so) I would personally be wary of it.

I agree. I'm wondering if it wouldn't be easier to generate the doc locally and push it to the repo.

It might be if I can't get automatic builds working, but I feel like this is quite a useful thing to have long term and I'm happy to put in the work to get it up and running while I have time. Let's reasses if I run out of steam on fixing it for any reason? Same here that I'm not certain of all the details of the deployment stage, there are important symlinks created and a javascript file is automatically edited so that the documentation version selector in the navigation bar works correctly, and so stable points to latest tagged ver etc.

[moustachio-belvedere]

I just pushed tag v0.9.3 and the stable documentation has now built correctly with the correct name in the the docs navigation bar.

It's fixed enough for now I think. This morning I'm going to make a test package for Literate.jl, will report back how it works out.

I will delete the tag for now and clean slate docs again so we can test to see if tagbot correctly triggers a stable docs build also, when we are ready to tag version on 0.9.3 on JuliaRegistrator.

[moustachio-belvedere]

Worst case, if tagbot does not trigger stable docs build, we remove tagbot, then all we have to do is tag manually after pushing to JuliaRegistrator and everything should work fine. Closing this for now, we can reopen or add new more specific issue if needed in future.