Improve rendering of nesting levels in spec docs

[bgilbert]

The config spec docs (for both Ignition and FCCT) have several levels of nested bullets, which are difficult to visually distinguish when reading the docs. See if we can tweak the CSS on the docs sites to make the levels more distinctive.

[Okeanos]

Sooooo … I had a possible idea about how to approach that and whipped up a technical solution towards the whole "how to target the spec pages" when rending Markdown via GH Pages using just-the-docs without messing too much with customization options (that all have to be maintained and make it difficult to keep the theme up to date).

Instead of having:

I think something like the following may improve the reading experience without you/us having to mess with the existing spec files:

I admit that the solution is somewhat … esoteric:

/*
 because we don't have a particular class at hand (or a unique id) to select the specification lists we do some
 CSS voodoo with selector syntax (https://www.w3.org/TR/selectors-3/#selectors) instead to target them based on context
 clues:
 select unordered lists that are preceded by an h1 element whose id attribute contains the substring "-specification-"
 */
h1[id*="-specification-"] ~ ul {
  ul {
    border-left: 1px solid $grey-lt-300;
  }

  li::before {
    content: unset;
    margin-left: unset;
    position: unset;
  }
}

I'm open to suggestions to make it prettier or attempt to solve it differently. However, from a glance at the docs of just-the-docs and Jekyll there doesn't appear to be an easy/simple way to simply inject a standard CSS-class into particular pages.

if you want to see it live go to http://okeanos.github.io/butane/ (I suggest using a private Browser window to circumvent caching issues with the stylesheet).

[bgilbert]

Thanks for working on this! I like the gray lines as visual guides. I wonder whether we should also keep the bullets though?

On the technical front, another approach is to put an empty <div id="spec-docs"></div> after the header and before the field descriptions. Then the CSS could select on #spec-docs + ul.

If you haven't seen it, Ignition just switched to automatic generation of the spec docs files (coreos/ignition#1588) and Butane will do so soon (#390). In principle the generator could produce HTML directly, though I think it's nice to continue rendering via Markdown if practical.

[Okeanos]

I hadn't see that, no. That looks like a very cool step forward and I am wondering (semi-related) how it would relate to #363 ?

The HTML injection (i.e. putting <div id="spec-docs"></div> into the Markdown document before rendering) is something I suppose could work. I didn't test it yet because I may have faultily arrived at the idea that the Markdown parser may strip that for some reason (even though HTML is technically valid within Markdown).

I would think it makes sense to put this on hold until #390 is through?

---

Which bullet points would you want to keep? Top level, all levels? It's going to be a little involved either way I think because the bullets themselves are rendered via ::before-CSS content injection and depending on where/how they should be appearing next to the line, the positioning could get a little awkward.

[bgilbert]

It's independent of #363. coreos/ignition#1588 intentionally didn't put the docs in the JSON schema, since a) the schema's notion of things like the requiredness of a field doesn't always match the user-facing behavior, and b) the Resource struct is used in multiple places in the spec but has different docs each time.

I did test the <div> trick and it seems to work.

I don't think this change needs to wait for #390, but it certainly could if you prefer.

I was thinking all bullets would be retained. I'm not 100% sure about doing so, but would be interested in seeing a screenshot if it's not a lot of work.

[Okeanos]

I had to modify the bullet position a little but otherwise it works surprisingly well. Changes are live under the same URL as before and also use the <div id="spec-docs"></div> solution (which is way robuster, thanks for suggesting it!).

[bgilbert]

That looks great! Let's aim to get the change into both Ignition and Butane.