docs: automatically generate depfile

We need to regenerate the docs if any of the rst-files are changed. So
let's add a simple extension to generate a depfile, so meson will pick
up any changes needed.

Reviewed-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Eric Engestrom <eric@igalia.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11494>

docs/_exts/depfile.py

@@ -0,0 +1,34 @@
+# Copyright © 2021 Collabora Ltd
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sub license, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice (including the
+# next paragraph) shall be included in all copies or substantial portions
+# of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
+# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+def create_depfile(app, env):
+    if not app.config.depfile:
+        return
+
+    with open(app.config.depfile, 'w') as f:
+        for doc in env.found_docs:
+            path = env.doc2path(doc)
+            f.write('{0}: {1}\n'.format(app.outdir, path))
+
+def setup(app):
+    app.add_config_value('depfile', None, 'env')
+    app.connect('env-updated', create_depfile)

docs/conf.py

@@ -40,6 +40,7 @@ sys.path.append(os.path.abspath('_exts'))
 # ones.
 extensions = [
     'bootstrap',
+    'depfile',
     'formatting',
     'hawkmoth',
     'nir',

docs/meson.build

@@ -1,8 +1,10 @@
 html_docs = custom_target(
   'html',
+  depfile: 'docs.d',
   depend_files: files('conf.py'),
-  command: [sphinx, '-b', 'html', '-q', meson.current_source_dir(),
-            '@OUTPUT@'],
+  command: [sphinx, '-b', 'html', '-q',
+            '-Ddepfile=@DEPFILE@',
+            meson.current_source_dir(), '@OUTPUT@'],
   output: 'html',
   build_by_default: get_option('html-docs').enabled(),
 )