Merge pull request #237557 from pennae/dedocbookify-nixos

nixos/doc: dedocbookify

3 files changed, 28 insertions, 109 deletions

diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
index bfd69ec05cb..2c80d1eaab8 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
@@ -207,7 +207,7 @@ class ManualDocBookRenderer(RendererMixin, DocBookRenderer):
                 raise RuntimeError(f"rendering {path}") from e
         return "".join(result)
     def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        conv = options.DocBookConverter(self._manpage_urls, self._revision, False, 'fragment',
+        conv = options.DocBookConverter(self._manpage_urls, self._revision, 'fragment',
                                         token.meta['list-id'], token.meta['id-prefix'])
         conv.add_options(token.meta['source'])
         return conv.finalize(fragment=True)
@@ -469,7 +469,7 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer):
         return "".join(outer)
 
     def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        conv = options.HTMLConverter(self._manpage_urls, self._revision, False,
+        conv = options.HTMLConverter(self._manpage_urls, self._revision,
                                      token.meta['list-id'], token.meta['id-prefix'],
                                      self._xref_targets)
         conv.add_options(token.meta['source'])
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
index 7637241322f..2813ffcf8bc 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
@@ -37,11 +37,10 @@ class BaseConverter(Converter[md.TR], Generic[md.TR]):
 
     _options: dict[str, RenderedOption]
 
-    def __init__(self, revision: str, markdown_by_default: bool):
+    def __init__(self, revision: str):
         super().__init__()
         self._options = {}
         self._revision = revision
-        self._markdown_by_default = markdown_by_default
 
     def _sorted_options(self) -> list[tuple[str, RenderedOption]]:
         keys = list(self._options.keys())
@@ -106,7 +105,7 @@ class BaseConverter(Converter[md.TR], Generic[md.TR]):
             return []
 
     def _render_description(self, desc: str | dict[str, str]) -> list[str]:
-        if isinstance(desc, str) and self._markdown_by_default:
+        if isinstance(desc, str):
             return [ self._render(desc) ] if desc else []
         elif isinstance(desc, dict) and desc.get('_type') == 'mdDoc':
             return [ self._render(desc['text']) ] if desc['text'] else []
@@ -198,35 +197,22 @@ class DocBookConverter(BaseConverter[OptionsDocBookRenderer]):
 
     def __init__(self, manpage_urls: Mapping[str, str],
                  revision: str,
-                 markdown_by_default: bool,
                  document_type: str,
                  varlist_id: str,
                  id_prefix: str):
-        super().__init__(revision, markdown_by_default)
+        super().__init__(revision)
         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._renderer._manpage_urls, self._revision, self._markdown_by_default, self._document_type,
+        return (self._renderer._manpage_urls, self._revision, self._document_type,
                 self._varlist_id, self._id_prefix)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> DocBookConverter:
         return cls(*a)
 
-    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:
-        if lit := option_is(option, key, 'literalDocBook'):
-            return [ f"<para><emphasis>{key.capitalize()}:</emphasis> {lit['text']}</para>" ]
-        else:
-            return super()._render_code(option, key)
-
-    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:
-        if isinstance(desc, str) and not self._markdown_by_default:
-            return [ f"<nixos:option-description><para>{desc}</para></nixos:option-description>" ]
-        else:
-            return super()._render_description(desc)
-
     def _related_packages_header(self) -> list[str]:
         return [
             "<para>",
@@ -300,19 +286,19 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]):
     _options_by_id: dict[str, str]
     _links_in_last_description: Optional[list[str]] = None
 
-    def __init__(self, revision: str, markdown_by_default: bool,
+    def __init__(self, revision: str,
                  *,
                  # only for parallel rendering
                  _options_by_id: Optional[dict[str, str]] = None):
-        super().__init__(revision, markdown_by_default)
+        super().__init__(revision)
         self._options_by_id = _options_by_id or {}
         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 (self._revision, { '_options_by_id': self._options_by_id })
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> ManpageConverter:
-        return cls(*a[0], **a[1])
+        return cls(a[0], **a[1])
 
     def _render_option(self, name: str, option: dict[str, Any]) -> RenderedOption:
         links = self._renderer.link_footnotes = []
@@ -326,20 +312,11 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]):
         return super().add_options(options)
 
     def _render_code(self, option: dict[str, Any], key: str) -> list[str]:
-        if lit := option_is(option, key, 'literalDocBook'):
-            raise RuntimeError("can't render manpages in the presence of docbook")
-        else:
-            try:
-                self._renderer.inline_code_is_quoted = False
-                return super()._render_code(option, key)
-            finally:
-                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:
-            raise RuntimeError("can't render manpages in the presence of docbook")
-        else:
-            return super()._render_description(desc)
+        try:
+            self._renderer.inline_code_is_quoted = False
+            return super()._render_code(option, key)
+        finally:
+            self._renderer.inline_code_is_quoted = True
 
     def _related_packages_header(self) -> list[str]:
         return [
@@ -420,32 +397,16 @@ class OptionsCommonMarkRenderer(OptionDocsRestrictions, CommonMarkRenderer):
 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)
+    def __init__(self, manpage_urls: Mapping[str, str], revision: str):
+        super().__init__(revision)
         self._renderer = OptionsCommonMarkRenderer(manpage_urls)
 
     def _parallel_render_prepare(self) -> Any:
-        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)
+        return (self._renderer._manpage_urls, self._revision)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> CommonMarkConverter:
         return cls(*a)
 
-    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:
-        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat
-        # incorrect, since users rely on it.
-        if lit := option_is(option, key, 'literalDocBook'):
-            return [ f"*{key.capitalize()}:* {lit['text']}" ]
-        else:
-            return super()._render_code(option, key)
-
-    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:
-        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat
-        # incorrect, since users rely on it.
-        if isinstance(desc, str) and not self._markdown_by_default:
-            return [ desc ]
-        else:
-            return super()._render_description(desc)
-
     def _related_packages_header(self) -> list[str]:
         return [ "*Related packages:*" ]
 
@@ -476,32 +437,16 @@ class OptionsAsciiDocRenderer(OptionDocsRestrictions, 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)
+    def __init__(self, manpage_urls: Mapping[str, str], revision: str):
+        super().__init__(revision)
         self._renderer = OptionsAsciiDocRenderer(manpage_urls)
 
     def _parallel_render_prepare(self) -> Any:
-        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)
+        return (self._renderer._manpage_urls, self._revision)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> AsciiDocConverter:
         return cls(*a)
 
-    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:
-        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat
-        # incorrect, since users rely on it.
-        if lit := option_is(option, key, 'literalDocBook'):
-            return [ f"*{key.capitalize()}:* {lit['text']}" ]
-        else:
-            return super()._render_code(option, key)
-
-    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:
-        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat
-        # incorrect, since users rely on it.
-        if isinstance(desc, str) and not self._markdown_by_default:
-            return [ desc ]
-        else:
-            return super()._render_description(desc)
-
     def _related_packages_header(self) -> list[str]:
         return [ "__Related packages:__" ]
 
@@ -541,33 +486,21 @@ class OptionsHTMLRenderer(OptionDocsRestrictions, HTMLRenderer):
 class HTMLConverter(BaseConverter[OptionsHTMLRenderer]):
     __option_block_separator__ = ""
 
-    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool,
+    def __init__(self, manpage_urls: Mapping[str, str], revision: str,
                  varlist_id: str, id_prefix: str, xref_targets: Mapping[str, XrefTarget]):
-        super().__init__(revision, markdown_by_default)
+        super().__init__(revision)
         self._xref_targets = xref_targets
         self._varlist_id = varlist_id
         self._id_prefix = id_prefix
         self._renderer = OptionsHTMLRenderer(manpage_urls, self._xref_targets)
 
     def _parallel_render_prepare(self) -> Any:
-        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default,
+        return (self._renderer._manpage_urls, self._revision,
                 self._varlist_id, self._id_prefix, self._xref_targets)
     @classmethod
     def _parallel_render_init_worker(cls, a: Any) -> HTMLConverter:
         return cls(*a)
 
-    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:
-        if lit := option_is(option, key, 'literalDocBook'):
-            raise RuntimeError("can't render html in the presence of docbook")
-        else:
-            return super()._render_code(option, key)
-
-    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:
-        if isinstance(desc, str) and not self._markdown_by_default:
-            raise RuntimeError("can't render html in the presence of docbook")
-        else:
-            return super()._render_description(desc)
-
     def _related_packages_header(self) -> list[str]:
         return [
             '<p><span class="emphasis"><em>Related packages:</em></span></p>',
@@ -635,7 +568,6 @@ def _build_cli_db(p: argparse.ArgumentParser) -> None:
     p.add_argument('--document-type', required=True)
     p.add_argument('--varlist-id', required=True)
     p.add_argument('--id-prefix', required=True)
-    p.add_argument('--markdown-by-default', default=False, action='store_true')
     p.add_argument("infile")
     p.add_argument("outfile")
 
@@ -647,14 +579,12 @@ def _build_cli_manpage(p: argparse.ArgumentParser) -> None:
 def _build_cli_commonmark(p: argparse.ArgumentParser) -> None:
     p.add_argument('--manpage-urls', required=True)
     p.add_argument('--revision', required=True)
-    p.add_argument('--markdown-by-default', default=False, action='store_true')
     p.add_argument("infile")
     p.add_argument("outfile")
 
 def _build_cli_asciidoc(p: argparse.ArgumentParser) -> None:
     p.add_argument('--manpage-urls', required=True)
     p.add_argument('--revision', required=True)
-    p.add_argument('--markdown-by-default', default=False, action='store_true')
     p.add_argument("infile")
     p.add_argument("outfile")
 
@@ -663,7 +593,6 @@ def _run_cli_db(args: argparse.Namespace) -> None:
         md = DocBookConverter(
             json.load(manpage_urls),
             revision = args.revision,
-            markdown_by_default = args.markdown_by_default,
             document_type = args.document_type,
             varlist_id = args.varlist_id,
             id_prefix = args.id_prefix)
@@ -674,11 +603,7 @@ def _run_cli_db(args: argparse.Namespace) -> None:
             f.write(md.finalize())
 
 def _run_cli_manpage(args: argparse.Namespace) -> None:
-    md = ManpageConverter(
-        revision = args.revision,
-        # manpage rendering only works if there's no docbook, so we can
-        # also set markdown_by_default with no ill effects.
-        markdown_by_default = True)
+    md = ManpageConverter(revision = args.revision)
 
     with open(args.infile, 'r') as f:
         md.add_options(json.load(f))
@@ -687,10 +612,7 @@ def _run_cli_manpage(args: argparse.Namespace) -> None:
 
 def _run_cli_commonmark(args: argparse.Namespace) -> None:
     with open(args.manpage_urls, 'r') as manpage_urls:
-        md = CommonMarkConverter(
-            json.load(manpage_urls),
-            revision = args.revision,
-            markdown_by_default = args.markdown_by_default)
+        md = CommonMarkConverter(json.load(manpage_urls), revision = args.revision)
 
         with open(args.infile, 'r') as f:
             md.add_options(json.load(f))
@@ -699,10 +621,7 @@ def _run_cli_commonmark(args: argparse.Namespace) -> None:
 
 def _run_cli_asciidoc(args: argparse.Namespace) -> None:
     with open(args.manpage_urls, 'r') as manpage_urls:
-        md = AsciiDocConverter(
-            json.load(manpage_urls),
-            revision = args.revision,
-            markdown_by_default = args.markdown_by_default)
+        md = AsciiDocConverter(json.load(manpage_urls), revision = args.revision)
 
         with open(args.infile, 'r') as f:
             md.add_options(json.load(f))
diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_options.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_options.py
index 9608ed63921..fed0b1a17ac 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/tests/test_options.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_options.py
@@ -4,7 +4,7 @@ from markdown_it.token import Token
 import pytest
 
 def test_option_headings() -> None:
-    c = nixos_render_docs.options.DocBookConverter({}, 'local', False, 'none', 'vars', 'opt-')
+    c = nixos_render_docs.options.DocBookConverter({}, 'local', 'none', 'vars', 'opt-')
     with pytest.raises(RuntimeError) as exc:
         c._render("# foo")
     assert exc.value.args[0] == 'md token not supported in options doc'