Updated rendering setup on Read the Docs

I updated the way we render Flow, Neos and Media documentation on Read the Docs today, to fix the recent failures.

  • Those errors were caused by an incompatibility between the used versions of docutils and sphinx-doc. Now we specify which versions we need, effectively upgrading sphinx-doc, fixing the error.
  • The Makefile and conf.py have been simplified and updated, too, fixing two Flow branches calling themselves dev-master along the way.
  • The best part, though: Through the use of .readthedocs.yaml in the Flow development collection repository we can now render the documentation from there, as opposed to from the neos/flow split repository like we did before. This has two effects: changes to documentation are rendered faster after a push and the “Edit on GitHub” links finally work as expected! :tada:
    For Neos (and Media) the last part was solved slightly different, as the use of a .readthedocs.yaml file in the repository root would not allow to render only one project from the repository. So instead the settings pointing to conf.py, requirements.txt and the needed Python version were done in the RTD UI…
  • I also have hidden a number of versions no longer supported (the docs are still there, but the no longer show in the version selector.)

For the other projects the “neos” user on RTD has access to, I switched the Python version to 3.x but did not change anything else yet:

The builds for these all fail, so they would need treatment along the lines of

and

with adjusted paths in .readthedocs.yaml. Feel free to tackle those, ideally starting with the lowest supported branch to enable rendering of potentially updated documentation…

4 Likes