Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix header formatting in Sphinx-based docs #1154

Open
j-f1 opened this issue Jan 9, 2020 · 1 comment · May be fixed by #1155
Open

Fix header formatting in Sphinx-based docs #1154

j-f1 opened this issue Jan 9, 2020 · 1 comment · May be fixed by #1155

Comments

@j-f1
Copy link
Contributor

j-f1 commented Jan 9, 2020

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

node.inner_html = "<code>#{CGI::escapeHTML(node.content.strip)}</code> "

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)

@Thibaut
Copy link
Member

Thibaut commented Jan 10, 2020

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).

@j-f1 j-f1 linked a pull request Jan 10, 2020 that will close this issue
15 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants