Add deployment of documentation on github pages to CI

[mschmidt87]

This fixes #184 .

First we build the documentation in one of the jobs (I simplified the command here) and place a .nojekyll file in the html folder (which tells github pages that we're not using jekyll as a static site builder).
In addition, the PR adds a deploy stage to travis CI, which will push the contents of doc/_build/html .

I followed the steps in this tutorial: https://medium.com/@FelipeFaria/sphinx-travis-ci-github-pages-full-integration-for-auto-docs-publishing-91ce93179e17

Update:
I also added a bit of simplification to the travis file:

• I refactored the documentation building line
• Instead of installing not extra requirements, we're installing the [dev] requirements in the last job so that we can skip the manual install of black, mypy, and flake8.

I also added references to the documentation to the README.

[jakobj]

awesome, thanks for implementing this!

it's hard for me to evaluate, can I somehow check the github pages generated by this? is the doc deployed every time travis runs? how does this work? does every new PR update the docs? is that what we want? sorry, i am not familiar with this infrastructure

[mschmidt87]

can I somehow check the github pages generated by this? is the doc deployed every time travis runs? how does this work? does every new PR update the docs? is that what we want? sorry, i am not familiar with this infrastructure

Yes, I was wondering, too, how we can actually check this PR, I honestly don't know.

In general, the deploy phase is skipped for PR builds, i.e., this will only be executed once a PR is merged into master and master is rebuilt in Travis. That means, only then the documentation is rebuild and deployed to github pages. I think, this is what we want, right?

Regarding versioned documentation, i.e., having a documentation for release version alongside with the latest documentation: I am not sure how to do that at the moment. Will have to investigate, but I am pretty sure it is possible.

[jakobj]

In general, the deploy phase is skipped for PR builds, i.e., this will only be executed once a PR is merged into master and master is rebuilt in Travis. That means, only then the documentation is rebuild and deployed to github pages. I think, this is what we want, right?

yes, that sounds like what we want! 👌 can you somehow force deploy for this specific PR or do we need to work on master? 😬

Regarding versioned documentation, i.e., having a documentation for release version alongside with the latest documentation: I am not sure how to do that at the moment. Will have to investigate, but I am pretty sure it is possible.

this would indeed be great! and if we have to trigger it manually once per release, that would also be fine.

[mschmidt87]

I don't think it's possible to trigger the deploy manually here, because PR builds just skip this phase altogether and there seems to be no option to circumvent this. (See here for documentation about deploy phases: https://docs.travis-ci.com/user/deployment#pull-requests )

The CI here also doesn't run, I am not sure what the reason for this is. I hesitate to just merge the PR like this, basically untested, but I don't know any other way. This seems a bit absurd.

[mschmidt87]

Maybe we can merge this first to a different branch (e.g. test_deploy) and reconfigure travis before so that travis is also run on test_deploy. Then, after merging, we can see if everything works.

[mschmidt87]

I found a different way to test this:

• I added this branch here to the branches that travis runs on each commit to trigger the deployment.
• This works fine and you can already see the result here: https://happy-algorithms-league.github.io/hal-cgp/ . This documentation publishes the documentation pushed to the gh-pages branch.

However, one problem remains: Currently, the deplog phase is run for each of the 4 jobs, which is a) unnecessary because we only need to run it once and b) fails for the job that does not install the doc requirements.
To change that, I think that we need to refactor the whole travis file a bit, but I am still figuring out how.

[mschmidt87]

Update: I think I figured out a way to achieve everything, but now the deploy phase is skipped for all jobs, even for the one that should execute it (py=3.8, DEP=[all]). I don't understand why and have created a thread in the Travis CI community forum to ask for help: https://travis-ci.community/t/conditional-deploy-in-build-matrix-does-not-work/9362?u=mschmidt87

[mschmidt87]

Update: I received a reply and could solve the issue (some simple syntax error).
Now everything is working. I removed this feature branch from the branches in travis CI again, so that the deployment is now only carried out on each commit to master.

For evidence that the pipeline is working, see the build job on this feature branch here: https://travis-ci.org/github/Happy-Algorithms-League/hal-cgp/builds/709031726
when you click on the 4 individual builds, you will see that the deployment is carried out on only one branch, namely the python 3.8, [all] build as intended. The documentation gets push to the gh-pages branch and published here: https://happy-algorithms-league.github.io/hal-cgp/

[jakobj]

two small suggestions, otherwise great!

[mschmidt87]

I incorporated your suggestion, @jakobj , and also added the missing file about basic usage to the docs. Seems I forgot to add it in #181

[jakobj]

looks great! 👍 and merging