Readthedocs setup

[TeresiaOlsson]

This is to explain and document what I'm doing with readthedocs to setup the structure to generate versioned API documentation for all repositories in the github organization.

It looks like many parts can be done using a copier template but some manual steps are still required for publishing because you have to link the readthedocs to the github repository.

[TeresiaOlsson]

First thing I did was to install the readthedocs app at the organization level. It can be managed here:
https://github.com/organizations/python-accelerator-middle-layer/settings/installations/156479191

Hope is that this will mean that if you create a readthedocs account using your github account it should automatically detect the repositories you have admin rights for and you can make a readthedocs project for the one you want to add.

[TeresiaOlsson]

@simoneliuzzo and @JeanLucPons Did one of you create the readthedocs project for the pyaml repository? Is it possible that you can add me as maintainer to it so I can see what settings you put?

I'm testing now to set it up for pyaml-cs-oa using this copier template https://github.com/python-accelerator-middle-layer/pyaml-repository-template to generate the API documentation so it easily can be added to every new repository.

It's still very basic but I want to try if I can get the page to publish before I start to move over the things you added for the pyaml repository.

[simoneliuzzo]

Dear Teresia,

I do not know how to do it. I recall simply committing in the pyaml repository.
Here is what I see in readthedocs:

I have apparently no power to select specific maintainers for the documentation. I think that anyone that has rights in pyaml can modify the files.

Please let me know what I should do! If I can I will do it!

[TeresiaOlsson]

Yes, that's the one! If you go to maintainers in the left menu you should be able to invite more people so they also can do the admin.

I managed to get it to run automatically for PRs for pyaml-cs-oa. Interestingly it worked by itself without needing any github workflow. Maybe because I installed the readthedocs app in the organization?

[TeresiaOlsson]

Here you can see it: python-accelerator-middle-layer/pyaml-cs-oa#26

Other tests fail for other reasons but it's quite convenient because I could just click on the link in the job and see the documentation it built.

[TeresiaOlsson]

Now I just need to make the page look pretty by copying over some things from the pyaml readthedocs.

[TeresiaOlsson]

Yes, that's the one! If you go to maintainers in the left menu you should be able to invite more people so they also can do the admin.

I managed to get it to run automatically for PRs for pyaml-cs-oa. Interestingly it worked by itself without needing any github workflow. Maybe because I installed the readthedocs app in the organization?

No. Probably the difference is that I just choose the default options and then it connected the repository. Maybe if we switch to that in the pyaml settings too we don't need the github workflow anymore because readthedocs will do it by itself.

[TeresiaOlsson]

It is a bit annoying with readthedocs what we can't automatically grant permissions to everyone in our maintainer list from github but we need to manually invite other maintainers for each repository...

[simoneliuzzo]

Dear @TeresiaOlsson,

I think I have invited you.

let me know

[TeresiaOlsson]

It worked. I also invited you to the pyaml-cs-oa so we can compare settings. So far I only have put the default settings I got when I created the project + added to also build on PRs so I could test without merging.