From 10f9716ac173f708f111da366f211afc60b49cea Mon Sep 17 00:00:00 2001
From: "Christian Y. Brenninkmeijer"
 <christian.brenninkmeijer@manchester.ac.uk>
Date: Tue, 11 May 2021 08:15:21 +0100
Subject: [PATCH] sphinx4 fixes

---
 doc/source/conf.py    | 27 +++++++++++++++++++++++++--
 requirements-test.txt |  2 +-
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 70d91690..2bb3d4ad 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -28,6 +28,7 @@
 # serve to show the default.
 
 import os
+import re
 import sys
 from sphinx.ext import apidoc
 
@@ -366,6 +367,29 @@
     "special-members": "__call__"
 }
 
+_package_base = "data_specification"
+
+
+# Automatically called by sphinx at startup
+def setup(app):
+    # NB: extra dot at end is deliberate!
+    trim = (_package_base + ".", "spinn_utilities.", "spinn_machine.")
+
+    # Magic to shorten the names of our classes to their public versions
+    def skip_handler(_app, what, name, obj, skip, _options):
+        if not skip and what == 'module' and hasattr(obj, "__module__"):
+            # Get parent module *and* check if our name is in it
+            m = re.sub(r'\.[a-z0-9_]+$', '', obj.__module__)
+            if any(m.startswith(prefix) for prefix in trim) and \
+                    name in dir(sys.modules[m]):
+                # It is, so update to say that's canonical location for
+                # documentation purposes
+                obj.__module__ = m
+        return skip  # We don't care to change this
+
+    # Connect the callback to the autodoc-skip-member event from apidoc
+    app.connect('autodoc-skip-member', skip_handler)
+
 
 def filtered_files(base, unfiltered_files_filename):
     with open(unfiltered_files_filename) as f:
@@ -384,7 +408,6 @@ def filtered_files(base, unfiltered_files_filename):
 
 _output_dir = os.path.abspath(".")
 _unfiltered_files = os.path.abspath("../unfiltered-files.txt")
-_package_base = "data_specification"
 
 # Do the rst generation; remove files which aren't in git first!
 for fl in os.listdir("."):
@@ -393,5 +416,5 @@ def filtered_files(base, unfiltered_files_filename):
         os.remove(fl)
 os.chdir("../..")  # WARNING! RELATIVE FILENAMES CHANGE MEANING HERE!
 apidoc.main([
-    '-o', _output_dir, _package_base,
+    '-q', '-o', _output_dir, _package_base,
     *filtered_files(_package_base, _unfiltered_files)])
diff --git a/requirements-test.txt b/requirements-test.txt
index d4cb29bc..cdf0cd64 100644
--- a/requirements-test.txt
+++ b/requirements-test.txt
@@ -18,4 +18,4 @@ flake8
 coverage >= 4.4, < 5.0
 # pytest will be brought in by pytest-cov
 pytest-cov
-sphinx >= 2
+sphinx >= 4