Run tests for code example in README.rst (for django)

README

# Real name of this file is README.rst but I don't want github to render the rst ;)

Blah blah blah

.. testsetup::

    # This prepare the django environment to run all the "testcode" in this file
    # This is not visible in the rendered README

    import os
    os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings'

    import django
    django.setup()

    from django.db import connection
    connection.creation.create_test_db(verbosity=0)  # I use sqlite3 inmemory
  
.. testcode::

  print('this python code will be tested because in `testcode`, but not displayed by github")
  
  
.. code-block::

  print('this python code will be tested because in `code-block` which is replaced by `testcode` in our bash cript")
  

.. code:: python

  print("this python code won't be tested because in `code`")

test-readme.sh

#!/usr/bin/env bash
# Run the tests included in the README.rst file

# Temporary directory to be used by sphinx
TMPDIR=.tmpdocs

# Will reset it before
rm -rf $TMPDIR
mkdir $TMPDIR

# We copy in it our file to be tested, replacing "code-block" by "testcode" (we need to do it
# because github don't display the "testcode" sections, but we want them to be displayed, and
# the tests only work on "testcode" sections.
sed -e 's/.. code-block:: python/.. testcode::/' README.rst > $TMPDIR/README.rst

# Create the smallest configuration file possible for shpinx
cat  > $TMPDIR/conf.py <<EOF
extensions = ['sphinx.ext.doctest']
master_doc = 'README'
EOF

# And we can run the tests
sphinx-build -q -c $TMPDIR -b doctest $TMPDIR $TMPDIR $TMPDIR/README.rst

# Save the exit status to return it at the end
ERROR=$?

# Clean our mess
rm -fr $TMPDIR

# We want to tell the world if something was wrong
exit $ERROR

test_readme.py

"""Test all examples from the README.rst file"""

import os
import subprocess

from unittest import TestCase


class ExamplesTestCase(TestCase):
    """Run all the example in the readme file"""

    def test_all(self):
        """The example are tested by running sphinx with the doctest plugin

        And it's done by running the ``test-readme.sh`` file, and in case of errors, the whole
        output is displayed and the test marked as failed.

        """

        test_file_dir = os.path.join(os.path.dirname(__file__), '..')
        test_file_path = os.path.join(test_file_dir, 'test-readme.sh')
        try:
            subprocess.check_output(
                [test_file_path],
                shell=True,
                stderr=subprocess.STDOUT,
                cwd=test_file_dir,
            )
        except subprocess.CalledProcessError as exception:

            try:
                output = 'Error while running examples in README.rst :\n\n%s' % \
                    exception.output.decode('utf-8')
            except Exception:  # pylint: disable=broad-except
                output = exception.output

            self.fail(output)