diff options
author | pennae <82953136+pennae@users.noreply.github.com> | 2023-06-19 14:05:03 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-06-19 14:05:03 +0200 |
commit | c8b4e5d557c997c441f67a7fc6960c21f76298ab (patch) | |
tree | ac7fe5f263b4d61886f9434964b6f3232eac04e7 /pkgs/tools/nix | |
parent | f2eabf314bf77dfc44a225cdacbf8edb5a411fbc (diff) | |
parent | 3e7649f01be8b7a4295bd414e6cb905affff7d66 (diff) |
Merge pull request #237557 from pennae/dedocbookify-nixos
nixos/doc: dedocbookify
Diffstat (limited to 'pkgs/tools/nix')
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 bfd69ec05cb8e..2c80d1eaab86f 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 7637241322f2f..2813ffcf8bc0d 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 9608ed6392188..fed0b1a17ac1a 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' |