Conversation
| /* Module member specification */ | ||
|
|
||
| .spec:not(.include), .spec.include details summary { | ||
| .spec { |
There was a problem hiding this comment.
For people devising markup this is a good example of why classes should not be used for vastly different contexts.
Previous to this commit the spec include classes were used on a div wrapping the whole include and its markup content. But otherwise the spec class was always used only on divs simply wrapping the source of structure items. This entailed this incredibly complex selector for styling structure items sources which, with the new structure, now boils down to a simple .spec.
Drup
left a comment
There was a problem hiding this comment.
The markup for includes was definitely clunky, this is much better.
@dbuenzli It would be super helpful if you could write some quick guidelines on top of the HTML rendered detailing the general philosophy guiding the placement of the classes and the shape of the markup (you explained it in your various PRs, but I think it should be in the code).
Move from:
```
div.odoc-include
div."spec include"
div.doc
content of doc string (may be multiple paragraphs)
details
summary
span.def
code
include defs
```
to
```
div.odoc-include
div.spec-doc
content of doc string
details
summary."spec include"
code
include defs
```
a56536e to
8941790
Compare
Not sure I can establish a general philosophy from gut feelings :-) But I can try to add something at some point another markup PR.
Do you have particular comments in mind ? The PR has been rebased. |
|
Thanks @dbuenzli! |
This PR is build on top of #607 the relevant commits are the 4 last ones (sorry for always proceeding that way but changing the markup bit-by-bit in different branches is too unconvenient).
The current structure of includes is quite involved and messy. For one non-inlined include we have:
This PR proposes to change the structure to
Except for the docstring of the include coming before the specification (it would have been nice to put in the
summary, but the content model disallows it). This more regular with other structure items which have the following markup:In particular structure item doc strings are always in a
spec-docdiv and thespecclass is always on elements spanning directly the source of structure items.I have adapted the
odoc.cssand checked that stuff like double includes like this one work. I took the oportunity to fix #586 along the way.