search

crate / crate-docs

Common build system, QA tools, style guides, and other meta miscellanies for doing docs at Crate.io.
Apache License 2.0
2 stars 1 forks source link

Improve our style guide wrt RST headings #75

Closed nomicode closed 3 years ago

nomicode commented 3 years ago

I spent some time today trying to rethink how we do things from a typography perspective. one of the things I noticed was that our style guide for the lower-level RST headings were poorly thought out

I looked at the RST spec, found the list of valid characters, and cut the list down to characters that actually resemble properly typeset underlines, and then ranked them by visual prominence so as to mirror the way that headings are typeset in a "rich text" document

the convention of using "=" and "-" was a bit of a limiting factor but I chose to work around that. the convention is so strong at Crate and so widely spread, it would be a poor use of time to try and change something so inconsequential

however, the lower level headings are a complete jumble with no consistency from file to file. most of them do not follow the style guide because they were written before the style guide existed. accordingly, improving our style guide for the lower-level headings is low-hanging fruit for improving our RST

amotl commented 3 years ago

SCNR. Just taking the chance here to drop my humble opinion about this. I would follow the guidelines as outlined on the Sphinx documentation at [1].

Regarding the legacy we would be fighting, it would be great to have a black-style formatter to align all documents with this automatically. Then, the effort required could be minimized.

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections

amotl commented 3 years ago

it would be great to have a black-style formatter

JFYI, there is rstfmt and blacken-docs, but I haven't looked into them yet. Specifically, if they would provide such an option to reformat heading styles consistently, it would be really awesome for any endeavors in this space.

nomicode commented 3 years ago

I will merge, per our discussion on Slack

those tools look very interesting! thank you! if you find a workable integration that is easy to implement/rollout I'd be happy with that. in fact, if we find a way to integrate into make check, that would provide a pretty neat and organic way of rolling out changes: the RST fixes would get applied as we work on the files during normal work (which, as mentioned above, is how I apply my RST fixes anyway)