From c5ae12de9974bfb6e51bf62bdf847168c0da69e9 Mon Sep 17 00:00:00 2001
From: Jani Nikula <jani@nikula.org>
Date: Fri, 31 Mar 2023 00:08:10 +0300
Subject: [PATCH] doc: require hawkmoth for the documentation build

Now that we have documentation deployed at GitHub Pages, and we no
longer have to rely on Clang being available at Read The Docs in the
future, require Hawkmoth for the documentation build.

The fallback automock has not been updated in ages, and the
documentation build doesn't even work properly with that anymore. Just
throw it out.
---
 doc/conf.py                  | 28 +++--------------
 doc/examples.rst             |  6 ----
 doc/ext/automock/__init__.py | 59 ------------------------------------
 test/update-examples.py      |  6 ----
 4 files changed, 5 insertions(+), 94 deletions(-)
 delete mode 100644 doc/ext/automock/__init__.py

diff --git a/doc/conf.py b/doc/conf.py
index 4653db30..7a93875c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -17,6 +17,9 @@
 sys.path.insert(0, os.path.abspath('..'))
 
 extensions = [
+    'hawkmoth',
+    'hawkmoth.ext.javadoc',
+    'hawkmoth.ext.napoleon',
     'sphinx.ext.intersphinx',
 ]
 
@@ -39,33 +42,12 @@
 # that this is not the same as Hawkmoth extension minimum version requirement.
 needs_sphinx = '4.4'
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-
-# Handle failing hawkmoth import gracefully to be able to build the
-# documentation on e.g. https://readthedocs.org/ which would otherwise fail due
-# to missing clang.
-
-# This is not a good example to follow in regular documentation.
-try:
-    import hawkmoth
+# Setup Clang on Read The Docs
+if 'READTHEDOCS' in os.environ:
     from hawkmoth.util import readthedocs
 
     readthedocs.clang_setup()
 
-    extensions.append('hawkmoth')
-    extensions.append('hawkmoth.ext.napoleon')
-    extensions.append('hawkmoth.ext.javadoc')
-    tags.add('have_hawkmoth')
-
-except ImportError:
-    sys.stderr.write('Warning: Failed to import hawkmoth. Mocking results.\n')
-    sys.path.insert(0, os.path.abspath('ext'))
-    # The mock extension will include the hawkmoth test suite expected results
-    # into the documentation instead of generating.
-    extensions.append('automock')
-
 hawkmoth_root = os.path.join(os.path.abspath(os.path.dirname(__file__)), '../test/examples')
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/examples.rst b/doc/examples.rst
index 9916a41f..6bfcdeeb 100644
--- a/doc/examples.rst
+++ b/doc/examples.rst
@@ -12,12 +12,6 @@ This page showcases Hawkmoth in action.
    :local:
    :depth: 1
 
-.. only:: not have_hawkmoth
-
-   .. note:: The documentation you are viewing was built without Hawkmoth and/or
-             its dependencies (perhaps on https://readthedocs.org/). The output
-             seen below was pre-generated statically using Hawkmoth, and should
-             closely reflect actual results.
 
 Overview
 --------
diff --git a/doc/ext/automock/__init__.py b/doc/ext/automock/__init__.py
deleted file mode 100644
index 6476bf22..00000000
--- a/doc/ext/automock/__init__.py
+++ /dev/null
@@ -1,59 +0,0 @@
-# Copyright (c) 2020, Jani Nikula <jani@nikula.org>
-# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
-"""
-Automock
-========
-
-Sphinx C Domain directive extension to mock Hawkmoth by reading the
-corresponding expected .rst test result instead of actual processing.
-
-This is not an example how to do documentation fallbacks for regular projects
-when Hawkmoth is not available.
-"""
-
-import os
-
-from docutils.parsers.rst import directives
-from sphinx.directives.other import Include
-
-class Automock(Include):
-    required_arguments = 1
-    optional_arguments = 100 # arbitrary limit
-
-    option_spec = {
-        'transform': directives.unchanged_required,
-        'clang': directives.unchanged_required,
-        'file': directives.unchanged_required,
-        'members': directives.unchanged,
-    }
-    has_content = False
-
-    def _get_filename(self):
-        return self.arguments[0]
-
-    def run(self):
-        # Use include directive implementation with .c -> .rst
-        base, extension = os.path.splitext(self._get_filename())
-        self.arguments[0] = '../test/' + base + '.rst'
-
-        return super(Include, self).run()
-
-class AutomockSymbol(Automock):
-    def _get_filename(self):
-        return self.options.get('file')
-
-def setup(app):
-    app.add_config_value('cautodoc_root', app.confdir, 'env', [str])
-    app.add_config_value('cautodoc_transformations', None, 'env', [dict])
-    app.add_config_value('cautodoc_clang', [], 'env', [list])
-    app.add_directive_to_domain('c', 'autodoc', Automock)
-    app.add_directive_to_domain('c', 'autovar', AutomockSymbol)
-    app.add_directive_to_domain('c', 'autotype', AutomockSymbol)
-    app.add_directive_to_domain('c', 'autostruct', AutomockSymbol)
-    app.add_directive_to_domain('c', 'autounion', AutomockSymbol)
-    app.add_directive_to_domain('c', 'autoenum', AutomockSymbol)
-    app.add_directive_to_domain('c', 'automacro', AutomockSymbol)
-    app.add_directive_to_domain('c', 'autofunction', AutomockSymbol)
-
-    return dict(version = '0',
-                parallel_read_safe = True, parallel_write_safe = True)
diff --git a/test/update-examples.py b/test/update-examples.py
index 58f760f3..9dc8019d 100755
--- a/test/update-examples.py
+++ b/test/update-examples.py
@@ -37,12 +37,6 @@ def print_header():
    :local:
    :depth: 1
 
-.. only:: not have_hawkmoth
-
-   .. note:: The documentation you are viewing was built without Hawkmoth and/or
-             its dependencies (perhaps on https://readthedocs.org/). The output
-             seen below was pre-generated statically using Hawkmoth, and should
-             closely reflect actual results.
 ''')
 
 def print_title(testcases):