Documentation #7886
open
What's the policy on URL stability for public documentation?
Added by Yan-Fa Li about 10 years ago.
Updated over 4 years ago.
Description
We're trying to decide whether to include links to documentation on ceph.com within the UI of the Calamari product. What's the policy at ceph.com for the stability of links? Is there a permalink to the most current version of the ceph documentation that is safe to use within a web page?
Should we include a full copy of the ceph sphinx docs within an ICE release for offline use and/or avoid the issue with stable URLs?
- Status changed from New to 4
- Assignee changed from John Wilkins to Neil Levine
The Ceph.com site uses the master branch by default, which changes somewhat frequently. A more stable approach would be to ensure that the URL you expect to bake into a release works properly on the "next" branch, but specify the point release. For example, for Ceph version 0.71, the URL would look like this: http://ceph.com/docs/v0.71/ We don't regularly update the versioned branches, so they are more stable over the long term.
- Assignee changed from Neil Levine to John Wilkins
Getting off master and using the last named release branch name as the default docs root makes total sense. Does sphinx allow us to do something more sophisticated, like having a 'latest' link that points to the most recent branch? We can then point the webpage link to that.
We could certainly have a "latest-release" link on the website and legislate that to be our 'stable' doc link...
- Status changed from 4 to New
Also available in: Atom
PDF