devdocs
devdocs copied to clipboard
Fix header formatting in Sphinx-based docs
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)
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).