devdocs icon indicating copy to clipboard operation
devdocs copied to clipboard

Fix header formatting in Sphinx-based docs

Open j-f1 opened this issue 5 years ago • 1 comments

The Sphinx clean_html filter removes all formatting from <dt> elements:

https://github.com/freeCodeCamp/devdocs/blob/58a0120697a701f2cb9ca87061ec7ef6fde3b013/lib/docs/filters/sphinx/clean_html.rb#L64

However, this is not entirely desirable since the formatting makes things look better. For example, the header for BaseException (original) is transformed from this:

exception BaseException

to this:

exception BaseException

cc @Thibaut since you might have a reason for implementing this this way. (no worries if you don’t reply though)

j-f1 avatar Jan 09 '20 17:01 j-f1

sphinx/clean_html.rb is used across a wide range of docs, and unfortunately I found the formatting of Sphinx docs to be very inconsistent, to the point that aggressively removing some of the markup felt the better compromise to make this code work across all the Sphinx docs.

If you change it, it's likely (but not guaranteed—that was a long time ago) to cause minor issues on some docs, but I think it's worth a try (considering I don't remember exactly why this was added and that the worst that could happen is some styling issues, not content breakage).

Thibaut avatar Jan 10 '20 14:01 Thibaut