From 00a1b41c3b5d61a4ce1ae862e691ea0cde8fd974 Mon Sep 17 00:00:00 2001 From: pennae Date: Wed, 25 Jan 2023 17:31:01 +0100 Subject: [PATCH] nixos-render-docs: add html comment plugins options do not use comments, but a number of manual chapters do. since we don't want to enable html just so we can then inspect the html and figure out whether it's a comment we'll instead add a plugin that detects comments natively. --- .../src/nixos_render_docs/md.py | 41 +++++++ .../src/tests/test_plugins.py | 108 ++++++++++++++++++ 2 files changed, 149 insertions(+) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py index 501bc92ff71c..3f4aa7c47679 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py @@ -261,6 +261,45 @@ def _inline_anchor_plugin(md: markdown_it.MarkdownIt) -> None: md.inline.ruler.before("link", "inline_anchor", inline_anchor) +def _inline_comment_plugin(md: markdown_it.MarkdownIt) -> None: + def inline_comment(state: markdown_it.rules_inline.StateInline, silent: bool) -> bool: + if state.src[state.pos : state.pos + 4] != '': # --> + state.pos = i + 3 + return True + + return False + + md.inline.ruler.after("autolink", "inline_comment", inline_comment) + +def _block_comment_plugin(md: markdown_it.MarkdownIt) -> None: + def block_comment(state: markdown_it.rules_block.StateBlock, startLine: int, endLine: int, + silent: bool) -> bool: + pos = state.bMarks[startLine] + state.tShift[startLine] + posMax = state.eMarks[startLine] + + if state.src[pos : pos + 4] != '': + state.line = nextLine + 1 + return True + + nextLine += 1 + + return False + + md.block.ruler.after("code", "block_comment", block_comment) + class Converter(ABC): __renderer__: Callable[[Mapping[str, str], markdown_it.MarkdownIt], Renderer] @@ -286,6 +325,8 @@ class Converter(ABC): self._md.use(deflist_plugin) self._md.use(myst_role_plugin) self._md.use(_inline_anchor_plugin) + self._md.use(_inline_comment_plugin) + self._md.use(_block_comment_plugin) self._md.enable(["smartquotes", "replacements"]) def _post_parse(self, tokens: list[Token]) -> list[Token]: diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py index 3866adbf8b15..4efcb9bdfc73 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py +++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py @@ -169,3 +169,111 @@ def test_inline_anchor_escaping() -> None: Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, content='', markup='', info='', meta={}, block=True, hidden=False) ] + +def test_inline_comment_basic() -> None: + c = Converter({}) + assert c._parse("a b") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + content='a b', markup='', info='', meta={}, block=True, hidden=False, + children=[ + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None, + content='a b', markup='', info='', meta={}, block=False, hidden=False) + ]), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + assert c._parse("a") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + content='a', markup='', info='', meta={}, block=True, hidden=False, + children=[ + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None, + content='a', markup='', info='', meta={}, block=False, hidden=False) + ]), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + +def test_inline_comment_does_not_nest_in_code() -> None: + c = Converter({}) + assert c._parse("`ac`") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + content='`ac`', markup='', info='', meta={}, block=True, hidden=False, + children=[ + Token(type='code_inline', tag='code', nesting=0, attrs={}, map=None, level=0, children=None, + content='ac', markup='`', info='', meta={}, block=False, hidden=False) + ]), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + +def test_inline_comment_does_not_nest_elsewhere() -> None: + c = Converter({}) + assert c._parse("*ac*") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + content='*ac*', markup='', info='', meta={}, block=True, hidden=False, + children=[ + Token(type='em_open', tag='em', nesting=1, attrs={}, map=None, level=0, children=None, + content='', markup='*', info='', meta={}, block=False, hidden=False), + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=1, children=None, + content='ac', markup='', info='', meta={}, block=False, hidden=False), + Token(type='em_close', tag='em', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='*', info='', meta={}, block=False, hidden=False) + ]), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + +def test_inline_comment_can_be_escaped() -> None: + c = Converter({}) + assert c._parse("a\\c") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + content='a\\c', markup='', info='', meta={}, block=True, hidden=False, + children=[ + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None, + content='ac', markup='', info='', meta={}, block=False, hidden=False) + ]), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + assert c._parse("a\\\\c") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + children=[ + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None, + content='a\\c', markup='', info='', meta={}, block=False, hidden=False) + ], + content='a\\\\c', markup='', info='', meta={}, block=True, hidden=False), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + assert c._parse("a\\\\\\c") == [ + Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False), + Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1, + children=[ + Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None, + content='a\\c', markup='', info='', meta={}, block=False, hidden=False) + ], + content='a\\\\\\c', markup='', info='', meta={}, block=True, hidden=False), + Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None, + content='', markup='', info='', meta={}, block=True, hidden=False) + ] + +def test_block_comment() -> None: + c = Converter({}) + assert c._parse("") == [] + assert c._parse("") == [] + assert c._parse("") == [] + assert c._parse("") == [] + assert c._parse("") == []