nixos-render-docs: don't use markdown-it RendererProtocol

our renderers carry significantly more state than markdown-it wants to
easily cater for, and the html renderer will need even more state still.
relying on the markdown-it-provided rendering functions has already
proven to be a nuisance, and since parsing and rendering are split well
enough we can just replace the rendering part with our own stuff outright.

this also frees us from the tyranny of having to set instance variables
before calling super().__init__ just to make sure that the renderer
creation callback has access to everything it needs.

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/asciidoc.py

···
 
 from .md import Renderer
 
-import markdown_it
 from markdown_it.token import Token
 from markdown_it.utils import OptionsDict
 
···
     _list_stack: list[List]
     _attrspans: list[str]
 
-    def __init__(self, manpage_urls: Mapping[str, str], parser: Optional[markdown_it.MarkdownIt] = None):
-        super().__init__(manpage_urls, parser)
+    def __init__(self, manpage_urls: Mapping[str, str]):
+        super().__init__(manpage_urls)
         self._parstack = [ Par("\n\n", "====") ]
         self._list_stack = []
         self._attrspans = []

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/commonmark.py

···
 
 from .md import md_escape, md_make_code, Renderer
 
-import markdown_it
 from markdown_it.token import Token
 from markdown_it.utils import OptionsDict
 
···
     _link_stack: list[str]
     _list_stack: list[List]
 
-    def __init__(self, manpage_urls: Mapping[str, str], parser: Optional[markdown_it.MarkdownIt] = None):
-        super().__init__(manpage_urls, parser)
+    def __init__(self, manpage_urls: Mapping[str, str]):
+        super().__init__(manpage_urls)
         self._parstack = [ Par("") ]
         self._link_stack = []
         self._list_stack = []

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py

···
     partintro_closed: bool = False
 
 class DocBookRenderer(Renderer):
-    __output__ = "docbook"
     _link_tags: list[str]
     _deflists: list[Deflist]
     _headings: list[Heading]
     _attrspans: list[str]
 
-    def __init__(self, manpage_urls: Mapping[str, str], parser: Optional[markdown_it.MarkdownIt] = None):
-        super().__init__(manpage_urls, parser)
+    def __init__(self, manpage_urls: Mapping[str, str]):
+        super().__init__(manpage_urls)
         self._link_tags = []
         self._deflists = []
         self._headings = []

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manpage.py

···
 # horizontal motion in a line) we do attempt to copy the style of mdoc(7) semantic requests
 # as appropriate for each markup element.
 class ManpageRenderer(Renderer):
-    __output__ = "man"
-
     # whether to emit mdoc .Ql equivalents for inline code or just the contents. this is
     # mainly used by the options manpage converter to not emit extra quotes in defaults
     # and examples where it's already clear from context that the following text is code.
···
     _list_stack: list[List]
     _font_stack: list[str]
 
-    def __init__(self, manpage_urls: Mapping[str, str], href_targets: dict[str, str],
-                 parser: Optional[markdown_it.MarkdownIt] = None):
-        super().__init__(manpage_urls, parser)
+    def __init__(self, manpage_urls: Mapping[str, str], href_targets: dict[str, str]):
+        super().__init__(manpage_urls)
         self._href_targets = href_targets
         self._link_stack = []
         self._do_parbreak_stack = []

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py

···
 class ManualDocBookRenderer(DocBookRenderer):
     _toplevel_tag: str
 
-    def __init__(self, toplevel_tag: str, manpage_urls: Mapping[str, str],
-                 parser: Optional[markdown_it.MarkdownIt] = None):
-        super().__init__(manpage_urls, parser)
+    def __init__(self, toplevel_tag: str, manpage_urls: Mapping[str, str]):
+        super().__init__(manpage_urls)
         self._toplevel_tag = toplevel_tag
         self.rules |= {
             'included_sections': lambda *args: self._included_thing("section", *args),
···
             self._headings[-1] = self._headings[-1]._replace(partintro_closed=True)
         # must nest properly for structural includes. this requires saving at least
         # the headings stack, but creating new renderers is cheap and much easier.
-        r = ManualDocBookRenderer(tag, self._manpage_urls, None)
+        r = ManualDocBookRenderer(tag, self._manpage_urls)
         for (included, path) in token.meta['included']:
             try:
                 result.append(r.render(included, options, env))
···
         info = f" language={quoteattr(token.info)}" if token.info != "" else ""
         return f"<programlisting{info}>\n{escape(token.content)}</programlisting>"
 
-class DocBookConverter(Converter):
-    def __renderer__(self, manpage_urls: Mapping[str, str],
-                     parser: Optional[markdown_it.MarkdownIt]) -> ManualDocBookRenderer:
-        return ManualDocBookRenderer('book', manpage_urls, parser)
-
+class DocBookConverter(Converter[ManualDocBookRenderer]):
     _base_paths: list[Path]
     _revision: str
 
     def __init__(self, manpage_urls: Mapping[str, str], revision: str):
-        super().__init__(manpage_urls)
+        super().__init__()
+        self._renderer = ManualDocBookRenderer('book', manpage_urls)
         self._revision = revision
 
     def convert(self, file: Path) -> str:
···
 
         try:
             conv = options.DocBookConverter(
-                self._manpage_urls, self._revision, False, 'fragment', varlist_id, id_prefix)
+                self._renderer._manpage_urls, self._revision, False, 'fragment', varlist_id, id_prefix)
             with open(self._base_paths[-1].parent / source, 'r') as f:
                 conv.add_options(json.load(f))
             token.meta['rendered-options'] = conv.finalize(fragment=True)

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py

···
 from abc import ABC
 from collections.abc import Mapping, MutableMapping, Sequence
-from typing import Any, Callable, cast, get_args, Iterable, Literal, NoReturn, Optional
+from typing import Any, Callable, cast, Generic, get_args, Iterable, Literal, NoReturn, Optional, TypeVar
 
 import dataclasses
 import re
···
 
 AdmonitionKind = Literal["note", "caution", "tip", "important", "warning"]
 
-class Renderer(markdown_it.renderer.RendererProtocol):
+class Renderer:
     _admonitions: dict[AdmonitionKind, tuple[RenderFn, RenderFn]]
     _admonition_stack: list[AdmonitionKind]
 
-    def __init__(self, manpage_urls: Mapping[str, str], parser: Optional[markdown_it.MarkdownIt] = None):
+    def __init__(self, manpage_urls: Mapping[str, str]):
         self._manpage_urls = manpage_urls
         self.rules = {
             'text': self.text,
···
 
     md.core.ruler.push("block_attr", block_attr)
 
-class Converter(ABC):
-    __renderer__: Callable[[Mapping[str, str], markdown_it.MarkdownIt], Renderer]
+TR = TypeVar('TR', bound='Renderer')
 
-    def __init__(self, manpage_urls: Mapping[str, str]):
-        self._manpage_urls = manpage_urls
+class Converter(ABC, Generic[TR]):
+    # we explicitly disable markdown-it rendering support and use our own entirely.
+    # rendering is well separated from parsing and our renderers carry much more state than
+    # markdown-it easily acknowledges as 'good' (unless we used the untyped env args to
+    # shuttle that state around, which is very fragile)
+    class ForbiddenRenderer(markdown_it.renderer.RendererProtocol):
+        __output__ = "none"
 
+        def __init__(self, parser: Optional[markdown_it.MarkdownIt]):
+            pass
+
+        def render(self, tokens: Sequence[Token], options: OptionsDict,
+                   env: MutableMapping[str, Any]) -> str:
+            raise NotImplementedError("do not use Converter._md.renderer. 'tis a silly place")
+
+    _renderer: TR
+
+    def __init__(self) -> None:
         self._md = markdown_it.MarkdownIt(
             "commonmark",
             {
···
                 'html': False,       # not useful since we target many formats
                 'typographer': True, # required for smartquotes
             },
-            renderer_cls=lambda parser: self.__renderer__(self._manpage_urls, parser)
+            renderer_cls=self.ForbiddenRenderer
         )
         self._md.use(
             container_plugin,
···
     def _render(self, src: str, env: Optional[MutableMapping[str, Any]] = None) -> str:
         env = {} if env is None else env
         tokens = self._parse(src, env)
-        return self._md.renderer.render(tokens, self._md.options, env) # type: ignore[no-any-return]
+        return self._renderer.render(tokens, self._md.options, env)

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py

···
 from collections.abc import Mapping, MutableMapping, Sequence
 from markdown_it.utils import OptionsDict
 from markdown_it.token import Token
-from typing import Any, Optional
+from typing import Any, Generic, Optional
 from urllib.parse import quote
 from xml.sax.saxutils import escape, quoteattr
 
 import markdown_it
 
+from . import md
 from . import parallel
 from .asciidoc import AsciiDocRenderer, asciidoc_escape
 from .commonmark import CommonMarkRenderer
···
         return None
     return option[key] # type: ignore[return-value]
 
-class BaseConverter(Converter):
+class BaseConverter(Converter[md.TR], Generic[md.TR]):
     __option_block_separator__: str
 
     _options: dict[str, RenderedOption]
 
-    def __init__(self, manpage_urls: Mapping[str, str],
-                 revision: str,
-                 markdown_by_default: bool):
-        super().__init__(manpage_urls)
+    def __init__(self, revision: str, markdown_by_default: bool):
+        super().__init__()
         self._options = {}
         self._revision = revision
         self._markdown_by_default = markdown_by_default
···
     # since it's good enough so far.
     @classmethod
     @abstractmethod
-    def _parallel_render_init_worker(cls, a: Any) -> BaseConverter: raise NotImplementedError()
+    def _parallel_render_init_worker(cls, a: Any) -> BaseConverter[md.TR]: raise NotImplementedError()
 
     def _render_option(self, name: str, option: dict[str, Any]) -> RenderedOption:
         try:
···
             raise Exception(f"Failed to render option {name}") from e
 
     @classmethod
-    def _parallel_render_step(cls, s: BaseConverter, a: Any) -> RenderedOption:
+    def _parallel_render_step(cls, s: BaseConverter[md.TR], a: Any) -> RenderedOption:
         return s._render_option(*a)
 
     def add_options(self, options: dict[str, Any]) -> None:
···
         token.meta['compact'] = False
         return super().bullet_list_open(token, tokens, i, options, env)
 
-class DocBookConverter(BaseConverter):
-    __renderer__ = OptionsDocBookRenderer
+class DocBookConverter(BaseConverter[OptionsDocBookRenderer]):
     __option_block_separator__ = ""
 
     def __init__(self, manpage_urls: Mapping[str, str],
···
                  document_type: str,
                  varlist_id: str,
                  id_prefix: str):
-        super().__init__(manpage_urls, revision, markdown_by_default)
+        super().__init__(revision, markdown_by_default)
+        self._renderer = OptionsDocBookRenderer(manpage_urls)
         self._document_type = document_type
         self._varlist_id = varlist_id
         self._id_prefix = id_prefix
 
     def _parallel_render_prepare(self) -> Any:
-        return (self._manpage_urls, self._revision, self._markdown_by_default, self._document_type,
+        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default, self._document_type,
                 self._varlist_id, self._id_prefix)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> DocBookConverter:
···
 class OptionsManpageRenderer(OptionDocsRestrictions, ManpageRenderer):
     pass
 
-class ManpageConverter(BaseConverter):
-    def __renderer__(self, manpage_urls: Mapping[str, str],
-                     parser: Optional[markdown_it.MarkdownIt] = None) -> OptionsManpageRenderer:
-        return OptionsManpageRenderer(manpage_urls, self._options_by_id, parser)
-
+class ManpageConverter(BaseConverter[OptionsManpageRenderer]):
     __option_block_separator__ = ".sp"
 
     _options_by_id: dict[str, str]
···
                  *,
                  # only for parallel rendering
                  _options_by_id: Optional[dict[str, str]] = None):
+        super().__init__(revision, markdown_by_default)
         self._options_by_id = _options_by_id or {}
-        super().__init__({}, revision, markdown_by_default)
+        self._renderer = OptionsManpageRenderer({}, self._options_by_id)
 
     def _parallel_render_prepare(self) -> Any:
         return ((self._revision, self._markdown_by_default), { '_options_by_id': self._options_by_id })
···
         return cls(*a[0], **a[1])
 
     def _render_option(self, name: str, option: dict[str, Any]) -> RenderedOption:
-        assert isinstance(self._md.renderer, OptionsManpageRenderer)
-        links = self._md.renderer.link_footnotes = []
+        links = self._renderer.link_footnotes = []
         result = super()._render_option(name, option)
-        self._md.renderer.link_footnotes = None
+        self._renderer.link_footnotes = None
         return result._replace(links=links)
 
     def add_options(self, options: dict[str, Any]) -> None:
···
         if lit := option_is(option, key, 'literalDocBook'):
             raise RuntimeError("can't render manpages in the presence of docbook")
         else:
-            assert isinstance(self._md.renderer, OptionsManpageRenderer)
             try:
-                self._md.renderer.inline_code_is_quoted = False
+                self._renderer.inline_code_is_quoted = False
                 return super()._render_code(option, key)
             finally:
-                self._md.renderer.inline_code_is_quoted = True
+                self._renderer.inline_code_is_quoted = True
 
     def _render_description(self, desc: str | dict[str, Any]) -> list[str]:
         if isinstance(desc, str) and not self._markdown_by_default:
···
 class OptionsCommonMarkRenderer(OptionDocsRestrictions, CommonMarkRenderer):
     pass
 
-class CommonMarkConverter(BaseConverter):
-    __renderer__ = OptionsCommonMarkRenderer
+class CommonMarkConverter(BaseConverter[OptionsCommonMarkRenderer]):
     __option_block_separator__ = ""
 
+    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool):
+        super().__init__(revision, markdown_by_default)
+        self._renderer = OptionsCommonMarkRenderer(manpage_urls)
+
     def _parallel_render_prepare(self) -> Any:
-        return (self._manpage_urls, self._revision, self._markdown_by_default)
+        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> CommonMarkConverter:
         return cls(*a)
···
 class OptionsAsciiDocRenderer(OptionDocsRestrictions, AsciiDocRenderer):
     pass
 
-class AsciiDocConverter(BaseConverter):
-    __renderer__ = AsciiDocRenderer
+class AsciiDocConverter(BaseConverter[OptionsAsciiDocRenderer]):
     __option_block_separator__ = ""
 
+    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool):
+        super().__init__(revision, markdown_by_default)
+        self._renderer = OptionsAsciiDocRenderer(manpage_urls)
+
     def _parallel_render_prepare(self) -> Any:
-        return (self._manpage_urls, self._revision, self._markdown_by_default)
+        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> AsciiDocConverter:
         return cls(*a)

pkgs/tools/nix/nixos-render-docs/src/tests/test_asciidoc.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 
 from sample_md import sample1
 
-class Converter(nixos_render_docs.md.Converter):
-    __renderer__ = nixos_render_docs.asciidoc.AsciiDocRenderer
+class Converter(nrd.md.Converter[nrd.asciidoc.AsciiDocRenderer]):
+    def __init__(self, manpage_urls: dict[str, str]):
+        super().__init__()
+        self._renderer = nrd.asciidoc.AsciiDocRenderer(manpage_urls)
 
 def test_lists() -> None:
     c = Converter({})

pkgs/tools/nix/nixos-render-docs/src/tests/test_commonmark.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 
 from sample_md import sample1
 
···
 
 import markdown_it
 
-class Converter(nixos_render_docs.md.Converter):
-    __renderer__ = nixos_render_docs.commonmark.CommonMarkRenderer
+class Converter(nrd.md.Converter[nrd.commonmark.CommonMarkRenderer]):
+    def __init__(self, manpage_urls: Mapping[str, str]):
+        super().__init__()
+        self._renderer = nrd.commonmark.CommonMarkRenderer(manpage_urls)
 
 # NOTE: in these tests we represent trailing spaces by ` ` and replace them with real space later,
 # since a number of editors will strip trailing whitespace on save and that would break the tests.

pkgs/tools/nix/nixos-render-docs/src/tests/test_headings.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 
 from markdown_it.token import Token
 
-class Converter(nixos_render_docs.md.Converter):
+class Converter(nrd.md.Converter[nrd.docbook.DocBookRenderer]):
     # actual renderer doesn't matter, we're just parsing.
-    __renderer__ = nixos_render_docs.docbook.DocBookRenderer
+    def __init__(self, manpage_urls: dict[str, str]) -> None:
+        super().__init__()
+        self._renderer = nrd.docbook.DocBookRenderer(manpage_urls)
 
 def test_heading_id_absent() -> None:
     c = Converter({})

pkgs/tools/nix/nixos-render-docs/src/tests/test_lists.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 import pytest
 
 from markdown_it.token import Token
 
-class Converter(nixos_render_docs.md.Converter):
+class Converter(nrd.md.Converter[nrd.docbook.DocBookRenderer]):
     # actual renderer doesn't matter, we're just parsing.
-    __renderer__ = nixos_render_docs.docbook.DocBookRenderer
+    def __init__(self, manpage_urls: dict[str, str]) -> None:
+        super().__init__()
+        self._renderer = nrd.docbook.DocBookRenderer(manpage_urls)
 
 @pytest.mark.parametrize("ordered", [True, False])
 def test_list_wide(ordered: bool) -> None:

pkgs/tools/nix/nixos-render-docs/src/tests/test_manpage.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 
 from sample_md import sample1
 
···
 
 import markdown_it
 
-class Converter(nixos_render_docs.md.Converter):
-    def __renderer__(self, manpage_urls: Mapping[str, str],
-                     parser: Optional[markdown_it.MarkdownIt] = None
-                     ) -> nixos_render_docs.manpage.ManpageRenderer:
-        return nixos_render_docs.manpage.ManpageRenderer(manpage_urls, self.options_by_id, parser)
-
+class Converter(nrd.md.Converter[nrd.manpage.ManpageRenderer]):
     def __init__(self, manpage_urls: Mapping[str, str], options_by_id: dict[str, str] = {}):
-        self.options_by_id = options_by_id
-        super().__init__(manpage_urls)
+        super().__init__()
+        self._renderer = nrd.manpage.ManpageRenderer(manpage_urls, options_by_id)
 
 def test_inline_code() -> None:
     c = Converter({})
···
 
 def test_collect_links() -> None:
     c = Converter({}, { '#foo': "bar" })
-    assert isinstance(c._md.renderer, nixos_render_docs.manpage.ManpageRenderer)
-    c._md.renderer.link_footnotes = []
+    c._renderer.link_footnotes = []
     assert c._render("[a](link1) [b](link2)") == "\\fBa\\fR[1]\\fR \\fBb\\fR[2]\\fR"
-    assert c._md.renderer.link_footnotes == ['link1', 'link2']
+    assert c._renderer.link_footnotes == ['link1', 'link2']
 
 def test_dedup_links() -> None:
     c = Converter({}, { '#foo': "bar" })
-    assert isinstance(c._md.renderer, nixos_render_docs.manpage.ManpageRenderer)
-    c._md.renderer.link_footnotes = []
+    c._renderer.link_footnotes = []
     assert c._render("[a](link) [b](link)") == "\\fBa\\fR[1]\\fR \\fBb\\fR[1]\\fR"
-    assert c._md.renderer.link_footnotes == ['link']
+    assert c._renderer.link_footnotes == ['link']
 
 def test_full() -> None:
     c = Converter({ 'man(1)': 'http://example.org' })

pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py

···
-import nixos_render_docs
+import nixos_render_docs as nrd
 
 from markdown_it.token import Token
 
-class Converter(nixos_render_docs.md.Converter):
+class Converter(nrd.md.Converter[nrd.docbook.DocBookRenderer]):
     # actual renderer doesn't matter, we're just parsing.
-    __renderer__ = nixos_render_docs.docbook.DocBookRenderer
+    def __init__(self, manpage_urls: dict[str, str]) -> None:
+        super().__init__()
+        self._renderer = nrd.docbook.DocBookRenderer(manpage_urls)
 
 def test_attr_span_parsing() -> None:
     c = Converter({})