Update Sphinx configuration to modern standards and add CI documentation build

.github/workflows/tests.yml

@@ -74,10 +74,36 @@ jobs:
           name: dist
           path: dist/
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+          cache: 'pip'
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install sphinx sphinx_rtd_theme
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v6
+        with:
+          name: docs
+          path: docs/_build/html/
+
   create-issue-on-failure:
     runs-on: ubuntu-latest
-    needs: [test, build]
-    if: always() && (needs.test.result == 'failure' || needs.test.result == 'cancelled' || needs.build.result == 'failure' || needs.build.result == 'cancelled') && github.event_name == 'schedule'
+    needs: [test, build, docs]
+    if: always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) && github.event_name == 'schedule'
     steps:
       - name: Create issue on failure
         uses: actions/github-script@v8

docs/conf.py

@@ -15,11 +15,26 @@
     'sphinx.ext.autodoc',
 ]
 
+# Mock imports for dependencies not needed for documentation
+autodoc_mock_imports = [
+    'cairocffi',
+    'flask',
+    'pytz',
+    'pyparsing',
+    'structlog',
+    'tzlocal',
+    'werkzeug',
+    'yaml',
+    'packaging',
+]
+
 templates_path = ['_templates']
 
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+}
 
-master_doc = 'index'
+root_doc = 'index'
 
 project = 'Graphite-Render'
 copyright = u'2014, Bruno Renié'
@@ -32,7 +47,6 @@
 pygments_style = 'sphinx'
 
 html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 htmlhelp_basename = 'Graphite-Renderdoc'
 
@@ -71,36 +85,11 @@ def format_args(self):
             return re.sub('requestContext, ', '', args)
 
 
-suppress_warnings = ['app.add_directive']
+suppress_warnings = ['app.add_directive', 'autodoc.import_object']
 
 
 def setup(app):
     app.add_autodocumenter(RenderFunctionDocumenter)
 
 
 add_module_names = False
-
-
-class Mock(object):
-    __all__ = []
-
-    def __init__(self, *args, **kwargs):
-        pass
-
-    def __call__(self, *args, **kwargs):
-        return Mock()
-
-    @classmethod
-    def __getattr__(cls, name):
-        if name in ('__file__', '__path__'):
-            return '/dev/null'
-        elif name[0] == name[0].upper():
-            mockType = type(name, (), {})
-            mockType.__module__ = __name__
-            return mockType
-        else:
-            return Mock()
-
-
-for mod_name in ['cairocffi']:
-    sys.modules[mod_name] = Mock()

docs/index.rst

@@ -1,5 +1,5 @@
 Graphite-Render documentation
-==========================
+=============================
 
 .. raw:: html