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

[Petri Latvala]

On Thu, Jun 20, 2019 at 02:38:19PM +0300, Arkadiusz Hiler wrote:
> 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')


LGTM.

Series is

Acked-by: Petri Latvala <petri.latvala at intel.com>