docs: split the test program documentation into sections

Signed-off-by: Thomas Wood <thomas.wood@intel.com>

5 files changed, 217 insertions, 83 deletions

diff --git a/docs/reference/intel-gpu-tools/.gitignore b/docs/reference/intel-gpu-tools/.gitignore
index 303929bc..00c1b023 100644
--- a/docs/reference/intel-gpu-tools/.gitignore
+++ b/docs/reference/intel-gpu-tools/.gitignore
@@ -3,7 +3,7 @@
 /html-build.stamp
 /html.stamp
 /html/
-/igt_test_programs.xml
+/igt_test_programs_*.xml
 /intel-gpu-tools-decl-list.txt
 /intel-gpu-tools-decl.txt
 /intel-gpu-tools-overrides.txt
diff --git a/docs/reference/intel-gpu-tools/Makefile.am b/docs/reference/intel-gpu-tools/Makefile.am
index e02308ae..cd9c771a 100644
--- a/docs/reference/intel-gpu-tools/Makefile.am
+++ b/docs/reference/intel-gpu-tools/Makefile.am
@@ -1,21 +1,47 @@
 ## Process this file with automake to produce Makefile.in
 
 TESTLISTS = $(top_builddir)/tests/single-tests.txt $(top_builddir)/tests/multi-tests.txt
-igt_test_programs.xml: igt_test_programs.xml.header $(TESTLISTS)
-	cat $(srcdir)/igt_test_programs.xml.header > $@; \
-	for test in `cat $(TESTLISTS)`; do \
-		if [ "$$test" = "TESTLIST" -o "$$test" = "END" ]; then \
-			continue; \
-		fi; \
+xml/igt_test_programs_%_programs.xml: $(TESTLISTS)
+	mkdir -p `dirname $@`
+	echo "<?xml version=\"1.0\"?>" > $@
+	echo "<!DOCTYPE refsect1 PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"" >> $@
+	echo "               \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $@
+	echo "[" >> $@
+	echo "  <!ENTITY % local.common.attrib \"xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $@
+	echo "  <!ENTITY version SYSTEM \"version.xml\">" >> $@
+	echo "]>" >> $@
+	echo "<refsect1>" >> $@
+	echo "<title>Programs</title>" >> $@
+	echo "<informaltable pgwide=\"1\" frame=\"none\"><tgroup cols=\"2\"><tbody>" >> $@
+	for test in `cat $(TESTLISTS) | tr ' ' '\n' | grep "^$*" | sort`; do \
+		echo "<row><entry role=\"program_name\">" >> $@; \
+		echo "<link linkend=\"$$test\">$$test</link></entry></row>" >> $@; \
+	done;
+	echo "</tbody></tgroup></informaltable>" >> $@
+	echo "</refsect1>" >> $@
+
+xml/igt_test_programs_%_description.xml: $(TESTLISTS)
+	mkdir -p `dirname $@`
+	echo "<?xml version=\"1.0\"?>" > $@
+	echo "<!DOCTYPE refsect1 PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"" >> $@
+	echo "               \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $@
+	echo "[" >> $@
+	echo "  <!ENTITY % local.common.attrib \"xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $@
+	echo "  <!ENTITY version SYSTEM \"version.xml\">" >> $@
+	echo "]>" >> $@
+	echo "<refsect1>" >> $@
+	echo "<title>Description</title>" >> $@
+	for test in `cat $(TESTLISTS) | tr ' ' '\n' | grep "^$*" | sort`; do \
 		echo "<refsect2 id=\"$$test\"><title>$$test</title><para>" >> $@; \
 		if [ -x $(top_builddir)/tests/$$test ]; then \
-			./$(top_builddir)/tests/$$test --help-description >> $@; \
+			testprog=$(top_builddir)/tests/$$test; \
 		else \
-			./$(top_srcdir)/tests/$$test --help-description >> $@; \
+			testprog=$(top_srcdir)/tests/$$test; \
 		fi; \
+		 ./$$testprog --help-description >> $@; \
 		echo "</para></refsect2>" >> $@; \
-	done; \
-	echo "</refsect1></refentry>" >> $@;
+	done;
+	echo "</refsect1>" >> $@
 
 # We require automake 1.6 at least.
 AUTOMAKE_OPTIONS = 1.6
@@ -83,9 +109,32 @@ IGNORE_HFILES=gen6_render.h gen7_media.h gen7_render.h gen8_media.h \
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
 HTML_IMAGES=
 
+test_program_files = xml/igt_test_programs_core_description.xml \
+		     xml/igt_test_programs_core_programs.xml \
+		     xml/igt_test_programs_debugfs_description.xml \
+		     xml/igt_test_programs_debugfs_programs.xml \
+		     xml/igt_test_programs_drm_description.xml \
+		     xml/igt_test_programs_drm_programs.xml \
+		     xml/igt_test_programs_drv_description.xml \
+		     xml/igt_test_programs_drv_programs.xml \
+		     xml/igt_test_programs_gem_description.xml \
+		     xml/igt_test_programs_gem_programs.xml \
+		     xml/igt_test_programs_gen3_description.xml \
+		     xml/igt_test_programs_gen3_programs.xml \
+		     xml/igt_test_programs_kms_description.xml \
+		     xml/igt_test_programs_kms_programs.xml \
+		     xml/igt_test_programs_pm_description.xml \
+		     xml/igt_test_programs_pm_programs.xml \
+		     xml/igt_test_programs_prime_description.xml \
+		     xml/igt_test_programs_prime_programs.xml \
+		     xml/igt_test_programs_sysfs_description.xml \
+		     xml/igt_test_programs_sysfs_programs.xml \
+		     $(NULL)
+
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=igt_test_programs.xml
+content_files=igt_test_programs.xml $(test_program_files) \
+	      $(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -105,14 +154,14 @@ include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST += igt_test_programs.xml.header
+# EXTRA_DIST +=
 
 # Files not to distribute
 # for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
 # for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
-DISTCLEANFILES = $(DOC_MODULE)-sections.txt igt_test_programs.xml
+DISTCLEANFILES = $(DOC_MODULE)-sections.txt $(test_program_files)
 
-CLEANFILES += igt_test_programs.xml
+CLEANFILES += $(test_program_files)
 
 # Comment this out if you want 'make check' to test you doc status
 # and run some sanity checks
diff --git a/docs/reference/intel-gpu-tools/igt_test_programs.xml b/docs/reference/intel-gpu-tools/igt_test_programs.xml
new file mode 100644
index 00000000..29698942
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/igt_test_programs.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
+]>
+
+<chapter id="test-programs">
+  <title>Test Programs</title>
+
+  <refentry id="igt-test-programs-common-features">
+    <refnamediv>
+      <refname>Common Features</refname>
+      <refpurpose>Features available in all test programs</refpurpose>
+    </refnamediv>
+    <refsect1>
+      <title>Command Line Options</title>
+      <para>
+        All tests support the following command line options:
+
+        <variablelist>
+          <varlistentry>
+            <term><option>--list-subtests</option></term>
+            <listitem><para>
+                list the available subtests and exit
+            </para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>--run-subtest <replaceable>subtest</replaceable></option></term>
+            <listitem><para>
+                run the specified subtest
+            </para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>--debug</option></term>
+            <listitem><para>
+                print extra debugging information when running tests
+            </para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>--help-description</option></term>
+            <listitem><para>
+                print a short description of the test and exit
+            </para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>--help</option></term>
+            <listitem><para>
+                print help and exit
+            </para></listitem>
+          </varlistentry>
+        </variablelist>
+      </para>
+    </refsect1>
+  </refentry>
+
+  <refentry id="igt-core-tests">
+    <refnamediv>
+      <refname>Core Tests</refname>
+      <refpurpose>Tests for core drm ioctls and behaviour.</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_core_programs.xml"/>
+    <xi:include href="igt_test_programs_core_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-drm-tests">
+    <refnamediv>
+      <refname>DRM Tests</refname>
+      <refpurpose>Tests for libdrm behaviour.</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_drm_programs.xml"/>
+    <xi:include href="igt_test_programs_drm_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-drv-tests">
+    <refnamediv>
+      <refname>DRV Tests</refname>
+      <refpurpose>Tests for overall driver behaviour.</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_drv_programs.xml"/>
+    <xi:include href="igt_test_programs_drv_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-gem-tests">
+    <refnamediv>
+      <refname>GEM Tests</refname>
+      <refpurpose>Tests for core drm ioctls and behaviour.</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_gem_programs.xml"/>
+    <xi:include href="igt_test_programs_gem_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-kms-tests">
+    <refnamediv>
+      <refname>KMS Tests</refname>
+      <refpurpose>Mode setting tests</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_kms_programs.xml"/>
+    <xi:include href="igt_test_programs_kms_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-pm-tests">
+    <refnamediv>
+      <refname>PM Tests</refname>
+      <refpurpose>Tests for power management features</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_pm_programs.xml"/>
+    <xi:include href="igt_test_programs_pm_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-prime-tests">
+    <refnamediv>
+      <refname>Prime Tests</refname>
+      <refpurpose>Buffer sharing tests</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_prime_programs.xml"/>
+    <xi:include href="igt_test_programs_prime_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-gen3-tests">
+    <refnamediv>
+      <refname>Gen 3 Tests</refname>
+      <refpurpose>Gen 3 specific tests</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_gen3_programs.xml"/>
+    <xi:include href="igt_test_programs_gen3_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-sysfs-tests">
+    <refnamediv>
+      <refname>Sysfs Tests</refname>
+      <refpurpose>Sysfs tests</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_sysfs_programs.xml"/>
+    <xi:include href="igt_test_programs_sysfs_description.xml"/>
+  </refentry>
+
+  <refentry id="igt-debugfs-tests">
+    <refnamediv>
+      <refname>Debugfs Tests</refname>
+      <refpurpose>Debugfs tests</refpurpose>
+    </refnamediv>
+    <xi:include href="igt_test_programs_debugfs_programs.xml"/>
+    <xi:include href="igt_test_programs_debugfs_description.xml"/>
+  </refentry>
+</chapter>
diff --git a/docs/reference/intel-gpu-tools/igt_test_programs.xml.header b/docs/reference/intel-gpu-tools/igt_test_programs.xml.header
deleted file mode 100644
index 662242ef..00000000
--- a/docs/reference/intel-gpu-tools/igt_test_programs.xml.header
+++ /dev/null
@@ -1,65 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
-  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-  <!ENTITY version SYSTEM "version.xml">
-]>
-<refentry id="intel-gpu-tools-test-programs">
-<refmeta>
-<refentrytitle role="top_of_page" id="intel-gpu-tools-test-programs.top_of_page">Test Programs</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo>
-  INTEL-GPU-TOOLS Library
-</refmiscinfo>
-</refmeta>
-<refnamediv>
-<refname>Tests Programs</refname>
-<refpurpose>Test cases for features and bugs</refpurpose>
-</refnamediv>
-
-<refsect1 id="intel-gpu-tools-test-programs.description" role="desc">
-<title role="desc.title">Description</title>
-Test cases for bugs, features and regression testing. All tests support the
-following common options:
-
-<variablelist>
-<varlistentry>
-<term><option>--list-subtests</option></term>
-<listitem><para>
-list the available subtests and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--run-subtest <replaceable>subtest</replaceable></option></term>
-<listitem><para>
-run the specified subtest
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--debug</option></term>
-<listitem><para>
-print extra debugging information when running tests
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--help-description</option></term>
-<listitem><para>
-print a short description of the test and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--help</option></term>
-<listitem><para>
-print help and exit
-</para></listitem>
-</varlistentry>
-</variablelist>
-</refsect1>
-
-<refsect1>
-<title>Programs</title>
diff --git a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml
index 07ced055..21150971 100644
--- a/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml
+++ b/docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml
@@ -14,7 +14,7 @@
   </bookinfo>
 
   <chapter>
-    <title>Intel GPU Tools</title>
+    <title>API Reference</title>
     <xi:include href="xml/drmtest.xml"/>
     <xi:include href="xml/igt_core.xml"/>
     <xi:include href="xml/igt_debugfs.xml"/>
@@ -25,10 +25,9 @@
     <xi:include href="xml/intel_batchbuffer.xml"/>
     <xi:include href="xml/intel_chipset.xml"/>
     <xi:include href="xml/intel_io.xml"/>
-    <xi:include href="xml/igt_test_programs.xml"/>
     <xi:include href="xml/igt_edid.xml"/>
-
   </chapter>
+  <xi:include href="xml/igt_test_programs.xml"/>
   <index id="api-index-full">
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>