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

@@ -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. <!-- reverse references in code -->
 
 #### Admonitions
 

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 <nixpkgs>/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)):

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 <nixpkgs>/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)):

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 "</dd>"
     def myst_role(self, token: Token, tokens: Sequence[Token], i: int) -> str:
+        # NixOS-specific roles are documented at <nixpkgs>/doc/README.md (with reverse reference)
         if token.meta['name'] == 'command':
             return f'<span class="command"><strong>{escape(token.content)}</strong></span>'
         if token.meta['name'] == 'file':

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 <nixpkgs>/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' ]:

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 <nixpkgs>/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)