doc/user: add a hack to get to the git version

meson doesn't have configuration_data() in vcs_tag so we can only replace one
string. sphinx cannot include things in-line.

Since we want the git version to be replaced in random places, we need to put
it into rst_prolog in conf.py - but that's where we neet to replace other
things too. Work around this by generating a mini python module that returns
the git version, then call that in conf.py.

Side-bonus: we now have access to the full commit and the abbreviated commit.
Not that anything actually uses this...

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/user/conf.py.in

@@ -12,10 +12,11 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import sys
+import os
+sys.path.insert(0, os.path.abspath('@BUILDDIR@'))
 
 # -- Project information -----------------------------------------------------
 
@@ -174,3 +175,23 @@ extlinks = { 'commit' :
 		('https://gitlab.freedesktop.org/libinput/libinput/commit/%s',
 			'git commit ')
 }
+
+# -- git version hack -------------------------------------------------
+#
+# meson doesn't take configuration_data() for vcs_tag, so we cannot replace
+# two substrings in the same file.
+#
+# sphinx cannot do ..include:: without linebreaks, so in-line replacements
+# are a no-go.
+#
+# Work around this by generating a mini python module in meson through
+# vcs_tag, then use that to generate the replacements in rst_prolog.
+
+import git_version
+
+rst_prolog = """
+   .. |git_version| replace:: :commit:`{}`
+   .. |git_version_full| replace:: :commit:`{}`
+
+""".format(git_version.get_git_version(),
+	   git_version.get_git_version_full)

doc/user/device-quirks.rst

@@ -116,8 +116,8 @@ List of supported device quirks
 ------------------------------------------------------------------------------
 
 This list is a guide for developers to ease the process of submitting
-patches upstream. This section shows device quirks supported in git
+patches upstream. This section shows device quirks supported in
-commit @includedoc git-version.dox
+|git_version|.
 
 .. warning:: Quirks are internal API and may change at any time for any reason.
              No guarantee is given that any quirk below works on your version of

doc/user/git_version.py.in

@@ -0,0 +1,5 @@
+def get_git_version():
+	return "__GIT_VERSION__"[:7]
+
+def get_git_version_full():
+	return "__GIT_VERSION__"

doc/user/index.rst

@@ -68,4 +68,4 @@ file for the full license information.
 .....
 About
 .....
-Documentation generated from :commit:`__GIT_VERSION__`.
+Documentation generated from |git_version|

doc/user/meson.build

@@ -7,6 +7,13 @@ endif
 sphinx_config = configuration_data()
 sphinx_config.set('PROJECT_NAME', meson.project_name())
 sphinx_config.set('PROJECT_VERSION', meson.project_version())
+sphinx_config.set('BUILDDIR', meson.current_build_dir())
+
+git_version_page = vcs_tag(command : ['git', 'log', '-1', '--format=%H'],
+			   fallback : 'unknown',
+			   input : 'git_version.py.in',
+			   output : 'git_version.py',
+			   replace_string: '__GIT_VERSION__')
 
 sphinx_conf_py = configure_file(input : 'conf.py.in',
 				output : 'conf.py',
@@ -68,6 +75,7 @@ src_rst = files(
 	'device-quirks.rst',
 	'faqs.rst',
 	'gestures.rst',
+	'index.rst',
 	'middle-button-emulation.rst',
 	'normalization-of-relative-motion.rst',
 	'palm-detection.rst',
@@ -100,17 +108,12 @@ src_sphinx = custom_target('sphinx-sources',
 			   command : [prg_install, '-t', '@OUTDIR@', '@INPUT@'],
 			   build_by_default: true)
 
-index_page = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
-		     fallback : 'unknown',
-		     input : 'index.rst',
-		     output : 'index.rst',
-		     replace_string: '__GIT_VERSION__')
 
 # drop '-a' once we are happy with all this
 # do not use -j, it breaks on Ubuntu
 sphinx_output_dir = 'Documentation'
 custom_target('sphinx',
-	      input : [ sphinx_conf_py, index_page ] + src_rst + src_extra,
+	      input : [ sphinx_conf_py, git_version_page ] + src_rst + src_extra,
 	      output : [ sphinx_output_dir ],
 	      command : [ sphinx, '-q', '-b', 'html', '-a',
 			  meson.current_build_dir(), sphinx_output_dir],