Gh pages

[asmodehn]

A simple attempt to integrate sphinx doc with github pages.

[fenollp]

If I understand this correctly, these two lines should be removed before merging otherwise any PR to master would update the docs.

The way tokens work though I believe this is true only for PRs opened where the author has commit rights to the repo.

[asmodehn]

good point... I m just discovering github actions, but maybe we want 2 workflows:

• one for pull request that just attempt a build (doctests and other can be added later on)
• one for push that build and deploy

[hwayne]

Right now the way it works is that any change to master rebuilds the Alloy docs on readthedocs.

[hwayne]

My main concern here is with conf.py: https://github.com/hwayne/alloydocs/blob/master/conf.py#L187. The intent there is to hide todos for the deployed version but show it to people on their local versions. Since that currently hardcodes readthedocs, it would show todos on github actions. Does actions set a special environmental variable we can use?

(We'd also need to make sure that this merge wouldn't break the RTD documentation, as that's where we're hosting the provision docs. Merging the github actions building would be more to make sure we could incorporate it seamlessly into the rest of the docs when the time is right.)

[asmodehn]

We can use a github defined variable like GITHUB_ACTIONS :
https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables
My fork deploys there : http://www.asmodehn.fr/alloydocs/

I also setup a build on RTD :
https://alloydocs-fork.readthedocs.io/en/latest/
Looks like it worked out of the box (didn't have to set anything...)

[asmodehn]

My personal concern however is with the python virtual environment setup.
We want both RTD and github (and local dev) to have the same version of every dependency, to avoid strange/hard-to-debug issues later on.

My personal choice for all my projects currently is pipenv, and it looks like RTD has had some discussion about it : readthedocs/readthedocs.org#3181

However I don't see it used at all in the build : https://readthedocs.org/projects/alloydocs-fork/builds/10889123/
There is also that lying around : readthedocs/readthedocs.org#4783

I think we would still need a .readthedocs.yml (maybe with a requirements.txt) file to be able to configure that properly: https://docs.readthedocs.io/en/stable/config-file/v2.html
Maybe even in the current master, so we can track the changes to the RTD config that this PR brings along...