diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 44c4bf78..af912527 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -311,16 +311,23 @@ def _render_summary_table(rows, style_param, include_headers=False): @dispatch def render_annotation(self, el: str) -> str: - """Special hook for rendering a type annotation. - Parameters - ---------- - el: - An object representing a type annotation. - """ + """Special hook for rendering a type annotation.""" + # Special case for None - it's used as shorthand for NoneType in type annotations + # e.g., "int | None" is common for Optional types + if el == "None": + if self.render_interlinks: + # Render as markdown link like other types + return f"[None](`None`)" + else: + # Render without backticks like any instance (e.g. 1, "a") + return "None" + + # For structural strings (brackets, operators, etc.), use existing logic return sanitize(el, escape_quotes=True) @dispatch def render_annotation(self, el: None) -> str: + # this is used to indicate no annotation, not the literal None return "" @dispatch diff --git a/quartodoc/tests/__snapshots__/test_renderers.ambr b/quartodoc/tests/__snapshots__/test_renderers.ambr index 2befccf0..26350008 100644 --- a/quartodoc/tests/__snapshots__/test_renderers.ambr +++ b/quartodoc/tests/__snapshots__/test_renderers.ambr @@ -13,15 +13,15 @@ ## Parameters {.doc-section .doc-section-parameters} - +--------+--------------------------------------------------------------------------------------+-------------------------------+------------+ - | Name | Type | Description | Default | - +========+======================================================================================+===============================+============+ - | x | [list](`list`)\[[C](`quartodoc.tests.example_signature.C`) \| [int](`int`) \| None\] | The x parameter | _required_ | - +--------+--------------------------------------------------------------------------------------+-------------------------------+------------+ - | y | [pathlib](`pathlib`).[Pathlib](`pathlib.Pathlib`) | The y parameter | _required_ | - +--------+--------------------------------------------------------------------------------------+-------------------------------+------------+ - | z | | The z parameter (unannotated) | _required_ | - +--------+--------------------------------------------------------------------------------------+-------------------------------+------------+ + +--------+------------------------------------------------------------------------------------------------+-------------------------------+------------+ + | Name | Type | Description | Default | + +========+================================================================================================+===============================+============+ + | x | [list](`list`)\[[C](`quartodoc.tests.example_signature.C`) \| [int](`int`) \| [None](`None`)\] | The x parameter | _required_ | + +--------+------------------------------------------------------------------------------------------------+-------------------------------+------------+ + | y | [pathlib](`pathlib`).[Pathlib](`pathlib.Pathlib`) | The y parameter | _required_ | + +--------+------------------------------------------------------------------------------------------------+-------------------------------+------------+ + | z | | The z parameter (unannotated) | _required_ | + +--------+------------------------------------------------------------------------------------------------+-------------------------------+------------+ ''' # --- # name: test_render_annotations_complex_no_interlinks diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py index 9efb3c99..7e3be118 100644 --- a/quartodoc/tests/test_renderers.py +++ b/quartodoc/tests/test_renderers.py @@ -213,6 +213,27 @@ def test_render_annotations_complex_no_interlinks(snapshot): assert res == snapshot +def test_render_annotation_none(): + """Test rendering of None in type annotations. + + None is special in type annotations - it's used as shorthand for NoneType + in annotations like 'int | None'. It should be rendered consistently with + other types like int and str. + """ + renderer_with_links = MdRenderer(render_interlinks=True) + renderer_no_links = MdRenderer(render_interlinks=False) + + # Test None with interlinks: should be markdown link + with_links = renderer_with_links.render_annotation("None") + assert ( + with_links == "[None](`None`)" + ), "None with interlinks should be markdown link" + + # Test None without interlinks: should have backticks + without_links = renderer_no_links.render_annotation("None") + assert without_links == "None", "None without interlinks should have no backticks" + + @pytest.mark.parametrize("children", ["embedded", "flat"]) def test_render_doc_class(snapshot, renderer, children): bp = blueprint(Auto(name="quartodoc.tests.example_class.C", children=children))