[igt-dev] [PATCH i-g-t] docs/reference: add links to testplan-based documentation

[Mauro Carvalho Chehab]

On Thu, 17 Aug 2023 23:08:24 +0530
"Modem, Bhanuprakash" <bhanuprakash.modem at intel.com> wrote:

> Hi Mauro,
> 
> On Thu-17-08-2023 03:05 pm, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab at kernel.org>
> > 
> > Instead of relying on runtime-based docs, use the documentation
> > parsed via testplan for i915, Xe and KMS tests.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab at kernel.org>
> > ---
> >   .../igt-gpu-tools/igt_test_programs.xml       | 63 ++++++++-----------
> >   docs/reference/igt-gpu-tools/meson.build      |  4 --
> >   2 files changed, 27 insertions(+), 40 deletions(-)
> > 
> > diff --git a/docs/reference/igt-gpu-tools/igt_test_programs.xml b/docs/reference/igt-gpu-tools/igt_test_programs.xml
> > index 92bc33ba83f6..51f8cac05f98 100644
> > --- a/docs/reference/igt-gpu-tools/igt_test_programs.xml
> > +++ b/docs/reference/igt-gpu-tools/igt_test_programs.xml
> > @@ -147,42 +147,6 @@
> >       <xi:include href="igt_test_programs_gem_description.xml"/>
> >     </refentry>
> >   
> > -  <refentry id="igt-gen3-tests">
> > -    <refnamediv>
> > -      <refname>Gen 3 Tests</refname>
> > -      <refpurpose>Tests specific to gen 3</refpurpose>
> > -    </refnamediv>
> > -    <xi:include href="igt_test_programs_gen3_programs.xml"/>
> > -    <xi:include href="igt_test_programs_gen3_description.xml"/>
> > -  </refentry>
> > -
> > -  <refentry id="igt-gen7-tests">
> > -    <refnamediv>
> > -      <refname>Gen 7 Tests</refname>
> > -      <refpurpose>Tests specific to gen 7</refpurpose>
> > -    </refnamediv>
> > -    <xi:include href="igt_test_programs_gen7_programs.xml"/>
> > -    <xi:include href="igt_test_programs_gen7_description.xml"/>
> > -  </refentry>
> > -
> > -  <refentry id="igt-i915-tests">
> > -    <refnamediv>
> > -      <refname>i915 Tests</refname>
> > -      <refpurpose>Tests for overall i915 driver behaviour</refpurpose>
> > -    </refnamediv>
> > -    <xi:include href="igt_test_programs_i915_programs.xml"/>
> > -    <xi:include href="igt_test_programs_i915_description.xml"/>
> > -  </refentry>
> > -
> > -  <refentry id="igt-kms-tests">
> > -    <refnamediv>
> > -      <refname>KMS Tests</refname>
> > -      <refpurpose>Tests for kernel mode setting</refpurpose>
> > -    </refnamediv>
> > -    <xi:include href="igt_test_programs_kms_programs.xml"/>
> > -    <xi:include href="igt_test_programs_kms_description.xml"/>
> > -  </refentry>
> > -
> >     <refentry id="igt-meta-tests">
> >       <refnamediv>
> >         <refname>Meta Tests</refname>
> > @@ -255,6 +219,33 @@
> >       <xi:include href="igt_test_programs_vgem_description.xml"/>
> >     </refentry>
> >   
> > +  <refentry id="igt-xe-tests">
> > +    <refnamediv>
> > +      <refname>
> > +          <ulink url="../testplan/xe_tests.html" type="http">Xe Tests</ulink>  
> 
> As the testplan is not inside the reference dir, the URL must be: 
> "../../../testplan/xe_tests.html"

The reference URL assumes the location where the docs will be installed.
So, if we have them installed under a "install_dir":


  $ meson --prefix `pwd`/install_dir build -Dxe_driver=enabled --reconfigure

We have:

	$ tree -d install_dir/share/gtk-doc/
	install_dir/share/gtk-doc/
	└── html
	    ├── igt-gpu-tools
	    └── testplan

So, "../testplan" is the path to go from "html/igt-gpu-tools" to the
location where xe_tests.html is located.

> Also, is there anyway to put these urls in index.html, instead of 
> opening igt-xe-tests.html and from there open the actual xe_tests.html?

With the current way this is generated, I'm not sure. I found it
hard to find a proper documentation about gtk-doc fields. Currently,
IGT relies on it to generate the index.html file.

Also meson integration (or gtk-doc) removes all files from the target
directory when building docs (html/igt-gpu-tools). 

One possible alternative would be to have a master index.html file
under install_dir/share/gtk-doc/html (or under some other place). I
avoided doing that (or some other doc reorg) as this could break any
scripts copying the documentation to some place.

> > +      </refname>
> > +      <refpurpose>Tests for the Intel Xe driver</refpurpose>
> > +    </refnamediv>
> > +  </refentry>
> > +
> > +  <refentry id="igt-i915-tests">
> > +    <refnamediv>
> > +      <refname>
> > +        <ulink url="../testplan/i915_tests.html" type="http">i915 Tests</ulink>
> > +      </refname>
> > +      <refpurpose>Tests for the Intel i915 driver</refpurpose>
> > +    </refnamediv>
> > +  </refentry>
> > +
> > +  <refentry id="igt-kms-tests">
> > +    <refnamediv>
> > +      <refname>
> > +        <ulink url="../testplan/kms_tests.html" type="http">KMS Tests</ulink>
> > +      </refname>
> > +      <refpurpose>Tests for kernel mode setting</refpurpose>
> > +    </refnamediv>
> > +  </refentry>
> > +
> >     <glossary>
> >       <title>Glossary</title>
> >   
> > diff --git a/docs/reference/igt-gpu-tools/meson.build b/docs/reference/igt-gpu-tools/meson.build
> > index 6b832ad279cf..9bb5ca7e0798 100644
> > --- a/docs/reference/igt-gpu-tools/meson.build
> > +++ b/docs/reference/igt-gpu-tools/meson.build
> > @@ -29,10 +29,6 @@ test_groups = [
> >   	'debugfs',
> >   	'drm',
> >   	'gem',
> > -	'gen3',
> > -	'gen7',
> > -	'i915',
> > -	'kms',  
> 
> Also, we must drop testdisplay, since it is already covered by kms tests.

OK, I'll remove it too.

Btw, there are other places generating broken links, so I suspect
that several of those "test_groups" aren't needed anymore. 

> 
> - Bhanu
> 
> >   	'meta',
> >   	'perf',
> >   	'pm',