adding self-build of docs (publishes to gh-pages branch)

[bmaranville]

We can build the docs ourselves instead of using readthedocs, which is an external point of failure.

This will make it easier to maintain and debug the documentation build (all code owners have access)

[arm61]

I think this is a better option, that all devs will have an access to, compared to the readthedocs.

[bmaranville]

It's not quite working yet - the module documentation is not being generated for some reason.

[bmaranville]

Ok, it's working now - see test build from this configuration at https://bmaranville.github.io/orsopy/

[andyfaff]

What will the URL be? Will it conflict with https://github.com/reflectivity/reflectivity.github.io?

[bmaranville]

By default, the new url would be https://reflectivity.github.io/orsopy , which seems to be automatically redirected to https://www.reflectometry.org/orsopy (currently resulting in a 404). We might have to fiddle with the settings on the redirects.

[andyfaff]

I think it's mergeable once the redirects are sorted. Who do we ask about that?

[bmaranville]

Actually it looks like it will work just fine - we will probably want to avoid making a folder called orsopy/ in our main website repo just to avoid conflicts. I uploaded a stub index.html to a new gh-pages branch on orsopy, and turned on github pages, and it is working.
See: https://www.reflectometry.org/orsopy

Discussion on folder vs. subrepo conflict: TL;DR: subrepo wins https://stackoverflow.com/a/26760818

[bmaranville]

I think it's mergeable once the redirects are sorted. Who do we ask about that?

You ask your delegated representative in the International Scattering Alliance, who is happy to help. Also, it's me.

[aglavic]

Great you got this going so quickly.

[aglavic]

I don't think we want to build it on every commit to main. The docs should be up-to-date with the latest released version to avoid confusion. This can be done the same way as we do with the PyPI release, based on the tag of the commit.

[bmaranville]

That seems like a good idea. Do we also need to add a test that tries to build the docs?

[aglavic]

I don't think so, the github action should show us if the build fails and you can still allow manual build.

[arm61]

Is this ready to merge?

[bmaranville]

Yes, I think it's ready to merge.

[arm61]

Do we know why the tests aren't passing?

[andyfaff]

There was a coverage timeout

[arm61]

That's what I thought. I don't have the power to tell Github to rerun them though, does someone have that power?

[bmaranville]

I did rerun them... they still failed. I will try again. I don't completely understand why there is a service we are uploading files to... isn't there an equivalent test that can run natively on Github Actions?

EDIT: I guess I can't re-run them. Never mind.

[arm61]

The service gives a nice visualisation of the coverage. It isn’t 100% required, but nice to have and I don’t think it can be mirrored on GitHub actions.

[bmaranville]

I have to say I really don't understand what is happening with the coveralls check... I copied the self-build-docs branch to my forked orsopy repository, created a pull request from it, and changed the pytest check so that coveralls runs for the forked repo, and it ran fine. Tests all passed.

Why is it not running here? Why the 422 error? Mysteries.

[arm61]

Let's merge this as is and then I will remove the coveralls thing from the Github action cause it is just a faff.

[bmaranville]

Hey, it worked! Check out https://www.reflectometry.org/orsopy/