DOC-1386 improve/tighten Markdown generation#68
Open
mabrown-hydrolix wants to merge 13 commits intodevfrom
Open
DOC-1386 improve/tighten Markdown generation#68mabrown-hydrolix wants to merge 13 commits intodevfrom
mabrown-hydrolix wants to merge 13 commits intodevfrom
Conversation
This is the first of several commits changing the Markdown emitted from the `click_extensions.py` code. The Markdown parser (`pymdown`) in use by the documentation team expects a single blank line between a paragraph and a list. This tightens up the Markdown emission code to remove extraneous newlines. Prior to this change, the resulting Markdown files sport the following violation count for Markdown syntax rules: 166 MD012 no-multiple-blanks 134 MD022 blanks-around-headings After this change, the report looks like this: 39 MD012 no-multiple-blanks 7 MD022 blanks-around-headings The subsequent commit fixes remaining violations of these rules. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md022/ - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md012/
This commit changes the `HdxGroup` and `HdxCommand` objects to suppressany output when no options table is necessary. The `_generate_options_table` function used to return an empty string which was always emitted. Now, instead, it returns `None` to indicate that no options table was found, allowing the caller to skip producing extra newlines under those circumstances. Prior to this change, the resulting Markdown files sport the following violation count for Markdown syntax rules: 39 MD012 no-multiple-blanks 7 MD022 blanks-around-headings There are no more cases of MD012 and MD022 in the resulting output now. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md022/ - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md012/
Switch from using Markdown emphasis to using a heading, whose level is derived from the click context depth. The `_generate_options_table` function already accepts the click context. In order to ensure that the Options section is placed correctly in a hierarchy, subordinate to the calling click context, we must add a single level to the depth. For example, if the calling object is an H3, we must calculate the Options section for the H3 as an H4, so that it nests correctly in the document structure. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md036/
Switch from using Markdown emphasis to using a subheading, whose level is derived from the click context depth. In order to ensure that the Usage and Examples sections are placed correctly in the document structure, add a single level to the depth calculated handled when processing an `HdxGroup` or `HdxCommand`. For example, if the object getting rendered to Markdown is at click command depth 2, it will be shown as an H3. We must therefore calculate the Usage and Examples sections as an H4, so that it nests correctly in the document structure. This commit fixes all `no-emphasis-as-heading` Markdown rule violations, MD036. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md036/
Generate a unique heading within each document. Use the click context to construct a heading that identifies the resource and command context. While this may appear to be a cosmetic fix, it enables Markdown rendering engines to make use of HTTP link anchors for locating a user in the document text. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md024/
The dialect of Markdown used by the ReadMe hosting (RMH) platform was called ReadMe Markdown (RDMD) and the RMH platform supported several keys in the front matter which we do not use in the MkDocs system. This commit removes the unnecessary front matter keys `slug`, `category` and `excerpt` while retaining the excerpt text as a subtitle element available to the new MkDocs system.
There are two changes in this commit: - The Markdown parser (`pymdown`) used for the documentation expects every code block to have a language specification [MD040]. - Using emphasis instead of a heading (H3, H4,...) is recommended against. In this case, since the code generates the heading levels from the structure of the commands in the `hdxcli` repository, simply drop the emphasis [MD036]. This is a small cosmetic change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md040/ - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md036/
The Markdown parser treats the underscore as a part of an emphasis according to the CommonMark specification. This means that without marking as code, the string "shadow_" is an unterminated emphasis. In this case, there is no closing underscore (`_`) and the parser is detecting the space adjacent to the sole underscore as some part of an emphasis element. This is a small cosmetic change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md037/
The Markdown parser in use with the documentation system (`pymdown`) expects lists not to be indented. This is a small cosmetic change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md007/
The Markdown parser (`pymdown`) in use by the documentation team expects a blank line between a paragraph and a list. This is a small cosmetic change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md032/
The Markdown parser (`pymdown`) in use by the documentation team expects a blank line between a paragraph and a list. This is a small cosmetic change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md032/
The Markdown parser (`pymdown`) in use by the documentation team expects - a blank line between a paragraph and a list [MD032] - no use of emphasis as the sole item in a paragraph or list [MD036] These are small cosmetic changes that allow the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md032/ - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md036/ Additionally, included in this commit is a nested list indenting change to work better with the Markdown rendering tool (Material for `mkdocs`) used by the Hydrolix docs system. This rendering tool expects nested unordered lists to have an indentation level of four (4) spaces. This deviates from the CommonMark specification which expects two (2) spaces as expressed in MD007. The deviation is intentional.
The Markdown parser (`pymdown`) in use by the documentation team expects only a single blank line between paragraphs [MD032]. Switch from using a block quotation with only a single emphasized string to display version number to a full line of text [MD036]. This is a small code change that allows the generated Markdown to satisfy the `pymarkdown` rules used by the Hydrolix docs system. - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md032/ - https://pymarkdown.readthedocs.io/en/latest/plugins/rule_md036/
mabrown-hydrolix
force-pushed
the
DOC-1386/hdxcli-markdown-generation-improvements
branch
from
d85653a to
2018f65
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
1 participant
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.
What changed?
This changeset generates stricter Markdown, drops several legacy front matter elements from generated documentation.
The commits remove violations of the following rules:
Why?
After these changes, the Markdown generated by this code can be committed directly into the Hydrolix docs system without further edits. This reduces the maintenance task for keeping up to date with the documentation generated by the
hdxclitoolchain.The removal of the front matter keys is simply evidence of switching to a new documentation platform. The new platform does not use the old front matter keys.
Additional information
Note that the stock
pymarkdownand CommonMarkul-indentrule expects two (2) space indentation for nested lists. This differs from the pattern used by the Hydrolix docs system. The Material for MkDocs system uses four (4) spaces. Since the primary system to handle the Markdown from thehdxcliutility is this one, the MD007 shall be configured to support 4 spaces.