On Wed, Oct 31, 2018 at 9:49 PM Noah Watkins <nwatkins@xxxxxxxxxx> wrote: > > Hi all, > > We have put together a first batch of changes to improve > documentation. Below are details on this set of changes. Please let us > know what you think... we're prepared to merge soon. > > PR: https://github.com/ceph/ceph/pull/24452 > > Live demo details: > > 1. The releases schedule page has been updated to be driven by a yaml > file so we can have a machine readable db of release information. The > format of the page is little different but can easily be tweaked: > > http://docs.ceph.com/ceph-prs/24452/releases/schedule/ > > 2. Edit on github link and warnings > > Every documentation page of a deployed version of the Ceph docs > (subject to some backporting) will have a new header that will be in a > 1 of 3 states: > > 1. Contains an edit on github link (master, supported releases: > mimic, luminous) > 2. No edit link, but a warning about unsupported version (e.g. > jewel, hammer, etc...) > 3. No edit link, but a notice about dev version of docs (e.g. master) Awesome. I was about to suggest that the master docs warning should be red too, but then I realised that for some pages (especially the release schedule, contribution notes), master is actually the right place to be and we'd want to warn people if they *weren't* looking at master. That distinction can probably be expressed in a short list of toplevel URL prefixes (the "master is the place to go" ones I see are /releases, /dev, and /architecture). So I guess there could be a hardcoded list of prefixes where a fourth type of header state ("You are on a stable branch but probably wanted master") would be displayed. Not that that should stop going forward with what's there today, it's a clear improvement. John > Important note about live demo: since these states are driven by the > version of the docs being viewed, the current PR is deployed with a > sampling of embedded test URLs that are selected randomly. You can > refresh any page a few times to preview each of the three states > above. Before merging we'll use the live URL information. > > - Noah
