diff --git a/mkquartodocs/extension.py b/mkquartodocs/extension.py index 0ef8352..c840078 100644 --- a/mkquartodocs/extension.py +++ b/mkquartodocs/extension.py @@ -434,12 +434,21 @@ def run(self, lines): cursor = cursor.advance_line(1) if any(x.startswith(":::") for x in outs): - # the ':::' is used in quarto to denote blocks but also used in - # mkdocstrings as a special 'domain-specific-syntax' ... so we need - # to remove them .... it also points to a bug in the preprocessor - # that let them go through ... - bads = [x for x in outs if x.startswith(":::")] - raise ValueError(f"Cell data contains admonition: {bads}") + # Check if these are unprocessed Quarto cell blocks (which would be a bug) + # vs. mkdocstrings syntax or other valid uses of ::: (which should be allowed) + potential_bugs = [] + for x in outs: + if x.startswith(":::"): + # Check if it looks like Quarto cell syntax that escaped processing + if ( + CELL_REGEX.match(x) + or CELL_ELEM_REGEX.match(x) + or CELL_ELEM_ALT_REGEX.match(x) + ): + potential_bugs.append(x) + + if potential_bugs: + raise ValueError(f"Unprocessed Quarto cell syntax found: {potential_bugs}") return outs diff --git a/tests/data/docs_issue69/docs/example.qmd b/tests/data/docs_issue69/docs/example.qmd new file mode 100644 index 0000000..1ae566e --- /dev/null +++ b/tests/data/docs_issue69/docs/example.qmd @@ -0,0 +1,11 @@ +--- +title: Example Quarto Document +--- + +# Example + +This is a simple quarto document. + +```{python} +print("Hello from Quarto!") +``` diff --git a/tests/data/docs_issue69/docs/index.md b/tests/data/docs_issue69/docs/index.md new file mode 100644 index 0000000..6bed466 --- /dev/null +++ b/tests/data/docs_issue69/docs/index.md @@ -0,0 +1,7 @@ +# Test for Issue #69 + +This is a regular markdown file with mkdocstrings syntax. + +::: pathlib.Path + +The above line uses mkdocstrings syntax to document the pathlib.Path class. diff --git a/tests/data/docs_issue69/expected_missing.txt b/tests/data/docs_issue69/expected_missing.txt new file mode 100644 index 0000000..d02078f --- /dev/null +++ b/tests/data/docs_issue69/expected_missing.txt @@ -0,0 +1,2 @@ +# The example.md generated from example.qmd should be cleaned up +./docs/example.md diff --git a/tests/data/docs_issue69/expected_output.txt b/tests/data/docs_issue69/expected_output.txt new file mode 100644 index 0000000..2c4b8f9 --- /dev/null +++ b/tests/data/docs_issue69/expected_output.txt @@ -0,0 +1,14 @@ +# Input files +./mkdocs.yml +./expected_output.txt +./expected_missing.txt +./docs +./docs/index.md +./docs/example.qmd + +# Site files +./site/404.html +./site/index.html +./site/example/index.html +./site/sitemap.xml +./site/sitemap.xml.gz diff --git a/tests/data/docs_issue69/mkdocs.yml b/tests/data/docs_issue69/mkdocs.yml new file mode 100644 index 0000000..3580f12 --- /dev/null +++ b/tests/data/docs_issue69/mkdocs.yml @@ -0,0 +1,7 @@ +site_name: Issue69 Test +plugins: + - mkquartodocs + - mkdocstrings: + handlers: + python: + paths: [.] diff --git a/tests/test_preprocessor.py b/tests/test_preprocessor.py index 325a2f9..bded1eb 100644 --- a/tests/test_preprocessor.py +++ b/tests/test_preprocessor.py @@ -115,3 +115,34 @@ def test_conversion_file(document): else: msg += ", For extra information set MKQUARTODOCS_TEST_DEBUG_OUT_DIR=1" raise AssertionError(msg) + + +def test_issue69_mkdocstrings_syntax(): + """Test that mkdocstrings syntax (::: prefix) is allowed. + + This is issue #69: https://github.com/jspaezp/mkquartodocs/issues/69 + The preprocessor should allow mkdocstrings syntax (which doesn't match + Quarto cell patterns) to pass through unchanged. + """ + preprocessor = AdmotionCellDataPreprocessor() + + # Markdown with mkdocstrings syntax + mkdocstrings_input = [ + "# API Documentation", + "", + "::: foo.main.hello", + "", + "This uses mkdocstrings syntax.", + "", + "::: another.module.function", + ] + + # This should NOT raise an error - mkdocstrings syntax should pass through + output = preprocessor.run(mkdocstrings_input) + + # The mkdocstrings lines should be preserved unchanged + assert "::: foo.main.hello" in output + assert "::: another.module.function" in output + + # Verify the output structure is preserved + assert len([line for line in output if line.startswith(":::")]) == 2