From 4f66d937a7b5bdaf70be94bed19df6530fd0e07c Mon Sep 17 00:00:00 2001
From: Leo Singer <leo.singer@ligo.org>
Date: Wed, 6 Sep 2023 07:59:25 -0400
Subject: [PATCH] Add documentation and unit tests for Markdown code blocks

Fixes #220.
---
 README.rst                | 17 +++++++++++++++++
 tests/test_doctestplus.py | 26 ++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/README.rst b/README.rst
index daf9477..d59148c 100644
--- a/README.rst
+++ b/README.rst
@@ -102,6 +102,23 @@ plugin and are set in ``doctest_optionflags`` in ``setup.cfg``. By default,
 doctest settings, see the `doctest documentation
 <https://docs.python.org/3/library/doctest.html#option-flags>`_.
 
+Running Tests in Markdown Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To run doctests in Markdown files, invoke pytest with the command line options
+``--doctest-plus --doctest-glob '*.md'``.
+
+If you write doctests inside `GitHub-style triple backtick fenced code blocks
+<https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#fenced-code-blocks>`_,
+then in order for pytest-doctest to find and run them you need to include an
+extra trailing newline inside your code blocks, like this::
+
+    ```pycon
+    >>> 1 + 2
+    2
+
+    ```
+
 Doctest Directives
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/tests/test_doctestplus.py b/tests/test_doctestplus.py
index 6e4148e..7b77f8a 100644
--- a/tests/test_doctestplus.py
+++ b/tests/test_doctestplus.py
@@ -593,6 +593,32 @@ def test_doctest_glob(testdir):
     ).assertoutcome(passed=1)
 
 
+@pytest.mark.xfail(reason='known issue, fenced code blocks require an extra trailing newline')
+def test_markdown_fenced_code(testdir):
+    testdir.makefile('.md', foo="""\
+```
+>>> 1 + 1
+2
+```
+""")
+    testdir.inline_run(
+        '--doctest-plus', '--doctest-glob', '*.md'
+    ).assertoutcome(passed=1)
+
+
+def test_markdown_fenced_code_with_extra_newline(testdir):
+    testdir.makefile('.md', foo="""\
+```
+>>> 1 + 1
+2
+
+```
+""")
+    testdir.inline_run(
+        '--doctest-plus', '--doctest-glob', '*.md'
+    ).assertoutcome(passed=1)
+
+
 def test_text_file_comments(testdir):
     testdir.makefile(
         '.md',