check.sh

#!/usr/bin/env sh
# Check missing references extension for proper functioning.

set +ex +o pipefail

DOCS=$(dirname $(dirname $0))

# Test first by writing the missing references file
git checkout $DOCS/conf.py
git checkout lib

git apply  - <<EOF
diff --git a/doc/conf.py b/doc/conf.py
index 954423aaf..d1742c427 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -101,6 +101,7 @@ else:
     autodoc_default_options = {'members': None, 'undoc-members': None}
 
 nitpicky = True
+missing_references_write_json = True
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
EOF

rm $DOCS/missing-references.json # This file is cached in the git index.

run_sphinx () {
    pushd $DOCS

    echo ""
    echo "Running sphinx..."
    echo ""

    if !(make clean html 2> .test-missing-references/$1); then
        EXITCODE=$?
        echo ""
        echo "exit code = $EXITCODE"
        echo ""
    else
        echo ""
        echo "exit code = 0"
        echo ""
    fi
    popd
}

echo "Create the missing reference file..."
run_sphinx sphinx.record.log


# Reset and check that the th missing reference file doesn't result in errors
git checkout $DOCS/conf.py
git apply - <<EOF
diff --git a/doc/conf.py b/doc/conf.py
index 954423aaf..7d6c6d8cc 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -101,6 +101,7 @@ else:
     autodoc_default_options = {'members': None, 'undoc-members': None}
 
 nitpicky = True
+missing_references_write_json = False
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),

EOF

echo "Check that the missing reference file works..."
run_sphinx sphinx.run.log

echo "Check that fixing a reference issues a warning..."
git apply - <<EOF
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 195b0ba73..96be1556e 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -6418,7 +6418,7 @@ optional.
             Default is ``None``.
 
             This parameter can be used to draw a histogram of data that has
-            already been binned, e.g. using `np.histogram` (by treating each
+            already been binned, e.g. using `numpy.histogram` (by treating each
             bin as a single point with a weight equal to its count) ::
 
                 counts, bins = np.histogram(data)

EOF
git checkout $DOCS/conf.py
run_sphinx sphinx.fix.log
git checkout lib/matplotlib/axes/_axes.py