[ENH/FIX] Support headings in nested parse#1102
Open
minijackson wants to merge 2 commits intoexecutablebooks:masterfrom
Open
[ENH/FIX] Support headings in nested parse#1102minijackson wants to merge 2 commits intoexecutablebooks:masterfrom
minijackson wants to merge 2 commits intoexecutablebooks:masterfrom
Conversation
This fixes using Markdown headings in Sphinx objects, like the `object`, `describe`, `py:data` directives, etc. This works by adding the heading to the temp root parent instead of at the end of the previous section from the main document. Fixes executablebooks#1050
This makes it so nested headings (in blockquotes, admonitions, etc.) generates rubrics that are offset by the current heading level, meaning that: ```markdown # Title ## Sub-title > Quote: > # Title in quote > Content. ``` will generate a rubric level 3 (level 1 + offset by 2 by the "Sub-title") inside the blockquote. This also makes those rubrics support the Sphinx option `heading-level`, for properly generating `<h1>`, `<h2>`, etc. A fix in the documentation was necessary, as an example generated a level-4 heading, whose id wasn't generated due to a myst_heading_anchors value too low.
7951c93 to
b2475db
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This fixes using Markdown headings in Sphinx objects, like the
object,describe,py:datadirectives, etc.; which fixes #1050.In summary, this should now work:
This works by adding the heading to the temp root parent instead of at the end of the previous section from the main document.
I've also added a change to the "heading to rubric" conversion in nested headings, whose levels now will be offset by the current heading level. So this:
will generate an
h3rubric inside the blockquote (offset by the "Sub-title" heading).This makes it consistent with the way it works with Markdown headings inside objects (which is consistent with RST's headings inside objects).
Tell me if you think this change is appropriate, if not I can always remove the commit.
I've also used the
heading-leveloption from Sphinx'rubricdirective, so that Sphinx generate appropriately leveled headers from those rubrics.Edit: for the offsetting of nested headers, I had to change a part of the documentation, because an example generated a level 4 headers, whose id wasn't generated due to a
myst_heading_anchorsvalue too low.