[hawkmoth] [PATCH 04/11] doc: rework the fallback code on failing to import hawkmoth

  • From: Jani Nikula <jani@xxxxxxxxxx>
  • To: hawkmoth@xxxxxxxxxxxxx
  • Date: Tue, 15 Dec 2020 21:00:01 +0200

The sphinx ..only directive is not as clean a conditional construct as
one would expect. The contents are parsed, and, unfortunately, warnings
are issued. For example, starting with sphinx 3:

doc/examples/example-10-macro.rst:2: WARNING: Duplicate C declaration, also 
defined at examples:2.

In order to remove the ..only directives for "not have_hawkmoth", we add
a mock directive extension to use instead of hawkmoth on failed
import. It will simply use the sphinx include directive to include the
corresponding .rst expected test results instead of using hawkmoth.
---
 doc/conf.py                  |  8 +++++--
 doc/examples.rst             | 36 ------------------------------
 doc/ext/automock/__init__.py | 43 ++++++++++++++++++++++++++++++++++++
 doc/update-examples          |  4 ----
 4 files changed, 49 insertions(+), 42 deletions(-)
 create mode 100644 doc/ext/automock/__init__.py

diff --git a/doc/conf.py b/doc/conf.py
index 97f45ec1b6bc..a86050f2480c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -41,7 +41,7 @@ with 
open(os.path.join(os.path.abspath(os.path.dirname(__file__)),
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
-# Handle failing hawkmoth.cautodoc import gracefully to be able to build the
+# 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 may not be a good example to follow in regular
 # documentation.
@@ -50,7 +50,11 @@ try:
     extensions.append('hawkmoth')
     tags.add('have_hawkmoth')
 except ImportError:
-    sys.stderr.write('Warning: Failed to import hawkmoth.\n')
+    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')
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
diff --git a/doc/examples.rst b/doc/examples.rst
index 6be635d2208f..cda4ff85be14 100644
--- a/doc/examples.rst
+++ b/doc/examples.rst
@@ -42,10 +42,6 @@ Output
 .. c:autodoc:: examples/example-10-macro.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-10-macro.rst
-
 Variable
 --------
 
@@ -69,10 +65,6 @@ Output
 .. c:autodoc:: examples/example-20-variable.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-20-variable.rst
-
 Typedef
 -------
 
@@ -96,10 +88,6 @@ Output
 .. c:autodoc:: examples/example-30-typedef.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-30-typedef.rst
-
 Enum
 ----
 
@@ -123,10 +111,6 @@ Output
 .. c:autodoc:: examples/example-40-enum.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-40-enum.rst
-
 Struct
 ------
 
@@ -150,10 +134,6 @@ Output
 .. c:autodoc:: examples/example-50-struct.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-50-struct.rst
-
 Function
 --------
 
@@ -177,10 +157,6 @@ Output
 .. c:autodoc:: examples/example-70-function.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-70-function.rst
-
 Preprocessor
 ------------
 
@@ -204,10 +180,6 @@ Output
 .. c:autodoc:: examples/example-70-preprocessor.c
    :clang: -DDEEP_THOUGHT
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-70-preprocessor.rst
-
 Compat
 ------
 
@@ -231,10 +203,6 @@ Output
 .. c:autodoc:: examples/example-80-compat.c
    :compat: javadoc-liberal
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-80-compat.rst
-
 Generic
 -------
 
@@ -258,7 +226,3 @@ Output
 .. c:autodoc:: examples/example-90-generic.c
    
 
-.. only:: not have_hawkmoth
-
-   .. include:: examples/example-90-generic.rst
-
diff --git a/doc/ext/automock/__init__.py b/doc/ext/automock/__init__.py
new file mode 100644
index 000000000000..148083d3904a
--- /dev/null
+++ b/doc/ext/automock/__init__.py
@@ -0,0 +1,43 @@
+# Copyright (c) 2020, Jani Nikula <jani@xxxxxxxxxx>
+# 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.
+"""
+
+import os
+
+from docutils.parsers.rst import directives
+from sphinx.directives.other import Include
+
+class Automock(Include):
+    required_argument = 1
+    optional_arguments = 1
+
+    # Allow passing a variable number of file patterns as arguments
+    final_argument_whitespace = True
+
+    option_spec = {
+        'compat': directives.unchanged_required,
+        'clang': directives.unchanged_required,
+    }
+    has_content = False
+
+    def run(self):
+        # Use include directive implementation with .c -> .rst
+        base, extension = os.path.splitext(self.arguments[0])
+        self.arguments[0] = base + '.rst'
+
+        return super(Include, self).run()
+
+def setup(app):
+    app.add_config_value('cautodoc_root', app.confdir, 'env')
+    app.add_config_value('cautodoc_compat', None, 'env')
+    app.add_config_value('cautodoc_clang', None, 'env')
+    app.add_directive_to_domain('c', 'autodoc', Automock)
+
+    return dict(version = '0',
+                parallel_read_safe = True, parallel_write_safe = True)
diff --git a/doc/update-examples b/doc/update-examples
index 414a2278d531..3bcab63e74b5 100755
--- a/doc/update-examples
+++ b/doc/update-examples
@@ -70,9 +70,5 @@ Output
 .. c:autodoc:: $input
 $(sed 's/^/   /' <<< $options)
 
-.. only:: not have_hawkmoth
-
-   .. include:: $static_output
-
 EOF
 done
-- 
2.20.1


Other related posts:

  • » [hawkmoth] [PATCH 04/11] doc: rework the fallback code on failing to import hawkmoth - Jani Nikula