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
andconf.py
have been simplified and updated, too, fixing two Flow branches calling themselvesdev-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 theneos/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!
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 toconf.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:
- SwiftMailer for Flow | Read the Docs
- Neos SEO | Read the Docs
- Neos RedirectHandler adapter | Read the Docs
- Neos Google Analytics | Read the Docs
- Flow Form Framework | Read the Docs
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…