[igt-dev] [PATCH i-g-t 5/5] docs: Embed subtest descriptions in the documentation

[Arkadiusz Hiler]

On Thu, Jun 20, 2019 at 02:11:59PM +0300, Petri Latvala wrote:
> On Thu, Jun 20, 2019 at 01:52:25PM +0300, Arkadiusz Hiler wrote:
> > On Thu, Jun 20, 2019 at 11:20:18AM +0300, Petri Latvala wrote:
> > > On Mon, Jun 17, 2019 at 01:54:43PM +0300, Arkadiusz Hiler wrote:
> > > > This rewrites generate_description_xml in Python, so that we generate
> > > > properly escaped XML. The switch also makes the code more manageable.
> > > > 
> > > > Changes in the generated docbook:
> > > > 
> > > > 1. subtests are not simply listed anymore, they are now another (sub)section
> > > > 
> > > > 2. subtests are now linkable,
> > > >    e.g. docs/igt-kms-tests.html#kms_hdmi_inject at inject-4k
> > > > 
> > > > 3. subtest's section now includes output of --describe
> > > > 
> > > > Python is required already by gtk-doc and we are not using anything
> > > > other than the standard library.
> > > 
> > > Python yes, but what about python3? My Debian installation is ancient
> > > even on Debian standards and gtk-doc-tools depends on python2. I'm too
> > > lazy to check if the version used by gitlab-CI depends on python3, so
> > > asking instead: Do you have a fork in gitlab for this? :P
> > 
> > It works on Fedora:
> > 
> > % head -n 1 $(which gtkdoc-mkhtml)
> > #!/usr/bin/python3
> > 
> > https://gitlab.freedesktop.org/drm/igt-gpu-tools/blob/master/.gitlab-ci.yml#L174
> > 
> > 
> > But for explicitness I can squash in:
> > 
> > diff --git a/docs/reference/igt-gpu-tools/meson.build b/docs/reference/igt-gpu-tools/meson.build
> > index e2bdc495..b3a4c0bd 100644
> > --- a/docs/reference/igt-gpu-tools/meson.build
> > +++ b/docs/reference/igt-gpu-tools/meson.build
> > @@ -45,6 +45,7 @@ test_groups = [
> >    'vgem',
> >  ]
> > 
> > +find_program('python3') # required by doc generators
> >  gen_description = find_program('generate_description_xml.py')
> >  gen_programs = find_program('generate_programs_xml.sh')
> 
> 
> For explicitness I'd prefer something the doc building can depend on
> to automatically not build them if you don't have python3.

I forgot that we have this weird conditional subdir().

diff --git a/meson.build b/meson.build
index 6268c58d..1d07af63 100644
--- a/meson.build
+++ b/meson.build
@@ -289,7 +289,8 @@ subdir('overlay')
 subdir('man')

 gtk_doc = dependency('gtk-doc', required : build_docs)
-if build_tests and gtk_doc.found()
+python3 = find_program('python3', required : build_docs)
+if build_tests and gtk_doc.found() and python3.found()
   subdir('docs')
 elif build_docs.enabled()
   error('Documentation requires building tests')