feat: filter markdown docs collection sources

README.md

@@ -53,6 +53,17 @@ To enable markdown python tests, pass the `--markdown-docs` flag to `pytest`:
 pytest --markdown-docs
 ```
 
+By default, both Python docstrings and standalone Markdown files are collected. To
+limit collection to one source, use one of the mutually exclusive scope options:
+
+```shell
+# Only code fences in .py docstrings
+pytest --markdown-docs --markdown-docs-only-docstrings
+
+# Only code fences in .md, .mdx, and .svx files
+pytest --markdown-docs --markdown-docs-only-text
+```
+
 You can also use the `markdown-docs` flag to filter *only* markdown-docs tests:
 
 ```shell

src/pytest_markdown_docs/plugin.py

@@ -435,15 +435,24 @@ def pytest_collect_file(
 ):
     if parent.config.option.markdowndocs:
         pathlib_path = pathlib.Path(str(file_path))  # pytest 7/8 compat
-        if pathlib_path.suffix == ".py":
+        only_docstrings = parent.config.option.markdowndocs_only_docstrings
+        only_text = parent.config.option.markdowndocs_only_text
+        if pathlib_path.suffix == ".py" and not only_text:
             return MarkdownDocstringCodeModule.from_parent(parent, path=pathlib_path)
-        elif pathlib_path.suffix in (".md", ".mdx", ".svx"):
+        elif pathlib_path.suffix in (".md", ".mdx", ".svx") and not only_docstrings:
             return MarkdownTextFile.from_parent(parent, path=pathlib_path)
 
     return None
 
 
 def pytest_configure(config):
+    if (
+        config.option.markdowndocs_only_docstrings
+        and config.option.markdowndocs_only_text
+    ):
+        raise pytest.UsageError(
+            "--markdown-docs-only-docstrings and --markdown-docs-only-text are mutually exclusive"
+        )
     config.addinivalue_line(
         "markers", f"{MARKER_NAME}: filter for pytest-markdown-docs generated tests"
     )
@@ -458,6 +467,20 @@ def pytest_addoption(parser: Parser) -> None:
         help="run ",
         dest="markdowndocs",
     )
+    group.addoption(
+        "--markdown-docs-only-docstrings",
+        action="store_true",
+        default=False,
+        help="collect markdown code fences only from Python docstrings",
+        dest="markdowndocs_only_docstrings",
+    )
+    group.addoption(
+        "--markdown-docs-only-text",
+        action="store_true",
+        default=False,
+        help="collect markdown code fences only from standalone Markdown files",
+        dest="markdowndocs_only_text",
+    )
     group.addoption(
         "--markdown-docs-syntax",
         action="store",

tests/plugin_test.py

@@ -85,6 +85,62 @@ def pytest_markdown_docs_globals():
     result.assert_outcomes(passed=1, failed=2)
 
 
+def test_only_text_collection(testdir):
+    testdir.makepyfile(
+        """
+        def docstring_test():
+            \"\"\"
+            ```python
+            assert False
+            ```
+            \"\"\"
+    """
+    )
+    testdir.makefile(
+        ".md",
+        """
+        ```python
+        assert True
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-only-text")
+    result.assert_outcomes(passed=1)
+
+
+def test_only_docstring_collection(testdir):
+    testdir.makepyfile(
+        """
+        def docstring_test():
+            \"\"\"
+            ```python
+            assert True
+            ```
+            \"\"\"
+    """
+    )
+    testdir.makefile(
+        ".md",
+        """
+        ```python
+        assert False
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-only-docstrings")
+    result.assert_outcomes(passed=1)
+
+
+def test_collection_scope_options_are_mutually_exclusive(testdir):
+    result = testdir.runpytest(
+        "--markdown-docs",
+        "--markdown-docs-only-docstrings",
+        "--markdown-docs-only-text",
+    )
+    assert result.ret != 0
+    result.stderr.fnmatch_lines(["*mutually exclusive*"])
+
+
 def test_continuation(testdir):
     testdir.makefile(
         ".md",