Automating Documentation Build Using ReadTheDocs.org Service?

[biergaizi]

Currently, the project documentation is rebuilt manually on each merge. If we don't constantly monitor openEMS-Project.git on every commit, the documentation may get outdated. For example, the Matlab/Octave documentation I submitted didn't show up on the website for several months. I don't think that asking @thliebig to rebuild the documentation on every merge is sustainable.

ReadTheDocs.org is a documentation build automation service, which can be triggered by a GitHub Actions. This is widely used by many FOSS projects such as numpy, We should consider using it to automate documentation update.

[thliebig]

Well yeah I think it is a good idea. I have not updated the documentation as I want the "official" online doc to reflect the current release?
But to have a nightly version would be good to, especially since I release way to rarely...

[biergaizi]

ReadTheDocs.org supports end-users to switch between "version x.y.z" and "latest" branches, ideal for this purpose.

A problem is that only the project owner has the permission to set it up. Let me see if I can set it up in my "fasterEMS" downstream first, once I managed to get a working configuration, we can enable that in the upstream repo.

[biergaizi]

I'm able to get the documentation working in my downstream fork, a preview is available here: https://openems-project-fork.readthedocs.io/en/latest/

Here's my plan for migrating documentation hosting to ReadTheDocs.org.

1. On your side, create a ReadTheDocs.org account (by logging in via GitHub) at https://app.readthedocs.org/accounts/login/?next=/dashboard/
2. Click "Add Project" -> "Configure Manually".
3. Confirm the warning: "Extra steps will be required to complete repository setup", click Continue.
4. Fill the Name, repository URL, and default branch, click Next.
5. On my side, I submit a Pull Request to introduce ReadTheDocs YAML files to the repo.
6. On your side, after confirming that documentation works, point docs.openems.de to ReadTheDocs.io's server, according to https://docs.readthedocs.com/platform/latest/guides/custom-domains.html.

At that point, the project's documentation hosting service would be fully migrated to ReadTheDocs. Running this migration provides several benefits:

1. Like GitHub Pages, it's a standard service used by many projects, with similar reliability.
2. Built-in multi-versioning support using the version selector. All future releases can be multi-versioned by adding new versions using the ReadTheDocs control panel (note that we can only use latest after the migration because old version tags are frozen, they lack the necessary YAML files to build the docs).
3. Automated documentation update on every commit to the master branch, and on every Pull Request (but since CSXCAD and openEMS are submodules, it's only effective for documentation in the main project repo only).

There are some potential disadvantages:

1. Project documentation is no longer hosted on GitHub Pages, but on ReadTheDocs.io server.
2. There's one more thing to do before releasing each version: enabling documentation in a new tag.
3. ReadTheDocs.org's free service inserts one banner ad at one of these two positions: bottom of the page, or bottom of the left sidepanel. Optionally, commercial product ads can be disabled through the control panel, but the banner is non-removable - community ads such as open-source conferences and project funding campaigns still exist, see service policy. You can find an example on my preview website.

I also considered an alternative self-hosting solution named sphinx-polyversion. This is a Sphinx launcher for building multiple documentation versions based on git tags, which can be added as a GitHub Actions. But it doesn't work, since git submodules are not supported. Further, without RTD, if we want documentation preview on every Pull Requests, it requires setting up a temporarily web host just for those pages, since the main GitHub Pages are "official" only.

Overall I think the benefits outweigh the disadvantages, in comparison to the workload of managing the multi-versioning manually. Let me know your thought.

[biergaizi]

I'm still waiting for your opinion on this potential change. The necessary changes on my side is already ready.

[thliebig]

Ah well I was waiting for your PR
I thought my initial comment made it already clear 😏