Feature #9103
closed
create a (generic) webservice to handle Sphinx documentation versions
Added by Alfredo Deza over 9 years ago.
Updated over 9 years ago.
Description
None of our docs allow a user to:
- Have a visual queue of what version of the docs they are seeing.
- be warned about development version of docs
- be warned about dated docs version
- switch easily between each version (e.g. "You are currently reading the development version docs, stable version docs are: 0.67.10, 0.82)
The webservice should be generic enough to accommodate other projects (ceph-deploy, calamari, etc...), and it should help to set what the
current stable version for each project is, and default to that, while handling nice urls for the docs, like:
/0.67.10/
/dev/
The calamari docs already include a version (albeit a rather verbose one including the git hash). I guess with a little cleverness we could add something to the sphinx build that conditionally puts a "warning, development version" header in at build time if the version string does not look like a nice branched one. But that part would just be part of the docs build, no external service needed.
Maintaining multiple versions in nice /a.b/ /c.d/ /latest/ subfolders is very desirable, but it sounds an awful lot like what readthedocs.org already does, do we need to reinvent it?
1.- Adding something to the Sphinx build is non-trivial. Sphinx extensions (the right way to do this) are very complex and hard to work with, the irony being that
documentation is not very good and it takes a massive amount of know-how to get things going. Anything that we do that alters the Sphinx build that is not part
of a Sphinx extension is going to add even more complexity to building docs (e.g. "run a script at the end of the build")
However, part of this ticket will mean crafting a Sphinx extension that will help by doing something very minimal to the output. It is just not possible to do all
the things listed in the ticket with just an extension.
2.- URL management is not only desirable, I believe it should be a requirement to properly server our docs. You are right in that ReadTheDocs already provides
for proper URL management, but how would you ago about installing/building Ceph on RTD? Take a look at ceph/admin/build-doc. It wouldn't be possible. RTD is
Python-centric and is easy for a Python project to get setup. Not so much for what we have for Ceph. There is no cohesive way of having our projects documentation
built/serve that accommodates them all.
If the idea of hosting everything in RTD is where we should be headed then lets take that decision and start working towards that goal?
- Status changed from New to Resolved
Also available in: Atom
PDF