From 3c20746f99537b0c8bf42ceef162fe73cdef7c77 Mon Sep 17 00:00:00 2001 From: Felix Stupp Date: Wed, 15 Jan 2025 11:54:42 +0000 Subject: [PATCH] doc: Cross-reference roles syntax doc & implementation reasoning: - (doc -> code) make it easier to find where those are implemented - to get easier insight if/what a specific renderer does with it - in case one wants to improve them, which seems likely as they are rather Nix/NixOS-specific - (took me too long to find their implementation) - (code -> doc) ensure changes to the code can be reflected in the doc - code authors might not know about the reference documentation or how to find it --- doc/README.md | 1 + .../ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py | 1 + .../ni/nixos-render-docs/src/nixos_render_docs/commonmark.py | 1 + pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/html.py | 1 + .../ni/nixos-render-docs/src/nixos_render_docs/manpage.py | 1 + pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/md.py | 1 + 6 files changed, 6 insertions(+) diff --git a/doc/README.md b/doc/README.md index 09a38d9dabbe..531c38acdfa5 100644 --- a/doc/README.md +++ b/doc/README.md @@ -108,6 +108,7 @@ A few markups for other kinds of literals are also available: These literal kinds are used mostly in NixOS option documentation. This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. +They are handled by `myst_role` defined per renderer. #### Admonitions diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py index 0c2531209876..dadcaa96b467 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py @@ -182,6 +182,7 @@ class AsciiDocRenderer(Renderer): self._leave_block() return "\n" def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str: + # NixOS-specific roles are documented at /doc/README.md (with reverse reference) self._parstack[-1].continuing = True content = asciidoc_escape(token.content) if token.meta['name'] == 'manpage' and (url := self._manpage_urls.get(token.content)): diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/commonmark.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/commonmark.py index 6287b60f0a51..7f31d0be44ae 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/commonmark.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/commonmark.py @@ -159,6 +159,7 @@ class CommonMarkRenderer(Renderer): self._leave_block() return "" def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str: + # NixOS-specific roles are documented at /doc/README.md (with reverse reference) self._parstack[-1].continuing = True content = md_make_code(token.content) if token.meta['name'] == 'manpage' and (url := self._manpage_urls.get(token.content)): diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/html.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/html.py index 1de511c7ce31..3e4ff1aedb7a 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/html.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/html.py @@ -136,6 +136,7 @@ class HTMLRenderer(Renderer): def dd_close(self, token: Token, tokens: Sequence[Token], i: int) -> str: return "" def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str: + # NixOS-specific roles are documented at /doc/README.md (with reverse reference) if token.meta['name'] == 'command': return f'{escape(token.content)}' if token.meta['name'] == 'file': diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/manpage.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/manpage.py index 024ec8d134dd..a3d6e791cabd 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/manpage.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/manpage.py @@ -253,6 +253,7 @@ class ManpageRenderer(Renderer): self._leave_block() return ".RE" def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str: + # NixOS-specific roles are documented at /doc/README.md (with reverse reference) if token.meta['name'] in [ 'command', 'env', 'option' ]: return f'\\fB{man_escape(token.content)}\\fP' elif token.meta['name'] in [ 'file', 'var' ]: diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/md.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/md.py index 894daf9ca9c7..93f07818b454 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/md.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/md.py @@ -228,6 +228,7 @@ class Renderer: def dd_close(self, token: Token, tokens: Sequence[Token], i: int) -> str: raise RuntimeError("md token not supported", token) def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str: + # NixOS-specific roles are documented at /doc/README.md (with reverse reference) raise RuntimeError("md token not supported", token) def attr_span_begin(self, token: Token, tokens: Sequence[Token], i: int) -> str: raise RuntimeError("md token not supported", token)