[PATCH i-g-t 1/2] lib: avoid < in gtkdoc comments

[PATCH i-g-t 1/2] lib: avoid < in gtkdoc comments

[Daniel Vetter]

For reasons entirely not clear to me meson gtkdoc runs in strict
xml parsing mode, whereas automake gtkdoc doesn't. And gtkdoc itself
is tooooooooo dense to correctly escape this stuff.

Paper around this.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 lib/igt_aux.c     | 4 ++--
 lib/igt_core.c    | 4 ++--
 lib/igt_debugfs.c | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/igt_aux.c b/lib/igt_aux.c
index 0bcf792c64e9..62b30ce0e01b 100644
--- a/lib/igt_aux.c
+++ b/lib/igt_aux.c
@@ -1000,7 +1000,7 @@ void igt_drop_root(void)
  * @var: var lookup to to enable this wait
  *
  * Waits for a key press when run interactively and when the corresponding debug
- * var is set in the --interactive-debug=<var> variable. Multiple keys
+ * var is set in the --interactive-debug=$var variable. Multiple keys
  * can be specified as a comma-separated list or alternatively "all" if a wait
  * should happen for all cases.
  *
@@ -1041,7 +1041,7 @@ void igt_debug_wait_for_keypress(const char *var)
  * @expected: message to be printed as expected behaviour before wait for keys Y/n
  *
  * Waits for a key press when run interactively and when the corresponding debug
- * var is set in the --interactive-debug=<var> variable. Multiple vars
+ * var is set in the --interactive-debug=$var variable. Multiple vars
  * can be specified as a comma-separated list or alternatively "all" if a wait
  * should happen for all cases.
  *
diff --git a/lib/igt_core.c b/lib/igt_core.c
index 6ce83becd18b..5f1d1d34dbc6 100644
--- a/lib/igt_core.c
+++ b/lib/igt_core.c
@@ -164,10 +164,10 @@
  *   test logic.
  *
  * - When adding a new feature test function which uses igt_skip() internally,
- *   use the <prefix>_require_<feature_name> naming scheme. When you
+ *   use the &lt;prefix>_require_&lt;feature_name> naming scheme. When you
  *   instead add a feature test function which returns a boolean, because your
  *   main test logic must take different actions depending upon the feature's
- *   availability, then instead use the <prefix>_has_<feature_name>.
+ *   availability, then instead use the &lt;prefix>_has_&lt;feature_name>.
  *
  * - As already mentioned eschew explicit error handling logic as much as
  *   possible. If your test absolutely has to handle the error of some function
diff --git a/lib/igt_debugfs.c b/lib/igt_debugfs.c
index 5670099f1480..156c1d45ef58 100644
--- a/lib/igt_debugfs.c
+++ b/lib/igt_debugfs.c
@@ -231,7 +231,7 @@ int igt_debugfs_dir(int device)
  * @mode: mode bits as used by open()
  *
  * This opens a debugfs file as a Unix file descriptor. The filename should be
- * relative to the drm device's root, i.e. without "drm/<minor>".
+ * relative to the drm device's root, i.e. without "drm/$minor".
  *
  * Returns:
  * The Unix file descriptor for the debugfs file or -1 if that didn't work out.
-- 
2.15.0

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH i-g-t 2/2] meson: gtkdoc support

[Daniel Vetter]

Bunch of neat improvements:

- xml generates correctly depend upon the test binaries
- no need to re-run autogen.sh when new chapters/functions get added,
  all handed by meson

Still one issue:

- the gtkdoc target doesn't depend upon the custom_target yet, hacked
  around using build_by_default: true

  This is an issue known to upstream already:

  https://github.com/mesonbuild/meson/issues/2148

v2: Bump meson version to 0.42, since that's the first release which
adds the build dir when running the gtkdoc tools, and hence allows
including generated files.

v2:
- Undo the bump, it's only needed for generated source files. Other
  generated files as input should work with 0.40 already.

- Generate version.xml from version.xml.in, which allows us to keep
  the &version; entity.

v3: Add github issue link.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 docs/meson.build                                   |  1 +
 .../intel-gpu-tools/generate_description_xml.sh    | 44 ++++++++++++
 .../intel-gpu-tools/generate_programs_xml.sh       | 22 ++++++
 docs/reference/intel-gpu-tools/meson.build         | 80 ++++++++++++++++++++++
 docs/reference/meson.build                         |  1 +
 meson.build                                        |  3 +
 meson.sh                                           |  2 +-
 tests/meson.build                                  |  6 +-
 8 files changed, 157 insertions(+), 2 deletions(-)
 create mode 100644 docs/meson.build
 create mode 100644 docs/reference/intel-gpu-tools/generate_description_xml.sh
 create mode 100755 docs/reference/intel-gpu-tools/generate_programs_xml.sh
 create mode 100644 docs/reference/intel-gpu-tools/meson.build
 create mode 100644 docs/reference/meson.build

diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 000000000000..ead14c4015d9
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1 @@
+subdir('reference')
diff --git a/docs/reference/intel-gpu-tools/generate_description_xml.sh b/docs/reference/intel-gpu-tools/generate_description_xml.sh
new file mode 100644
index 000000000000..8e39e0c4c289
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/generate_description_xml.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+
+output=$1
+filter=$2
+testlist=$3
+testdir=$(dirname $testlist)
+
+echo "<?xml version=\"1.0\"?>" > $output
+echo "<!DOCTYPE refsect1 PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"" >> $output
+echo "               \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $output
+echo "[" >> $output
+echo "  <!ENTITY % local.common.attrib \"xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $output
+echo "  <!ENTITY version SYSTEM \"version.xml\">" >> $output
+echo "]>" >> $output
+echo "<refsect1>" >> $output
+echo "<title>Description</title>" >> $output
+for test in `cat $testlist | tr ' ' '\n' | grep "^$filter" | sort`; do
+	echo "<refsect2 id=\"$test\"><title>" >> $output;
+	echo "$test" | perl -pe 's/(?<=_)$(KEYWORDS)(?=(_|\W))/<acronym>\1<\/acronym>/g' >> $output;
+	echo "</title><para><![CDATA[" >> $output;
+	testprog=$testdir/$test;
+	 ./$testprog --help-description >> $output;
+	echo "]]></para>" >> $output;
+	if ./$testprog --list-subtests > /dev/null ; then
+		echo "<refsect3><title>Subtests</title>" >> $output;
+		subtest_list=`./$testprog --list-subtests`;
+		subtest_count=`echo $subtest_list | wc -w`;
+		if [ $subtest_count -gt 100 ]; then
+			echo "<para>This test has over 100 subtests. " >> $output;
+			echo "Run <command>$test</command> <option>--list-subtests</option> to list them.</para>" >> $output;
+		else
+			echo "<simplelist>" >> $output;
+			for subtest in $subtest_list; do
+				echo "<member>" >> $output;
+				echo "$subtest" | perl -pe 's/\b$(KEYWORDS)\b/<acronym>\1<\/acronym>/g' >> $output;
+				echo "</member>" >> $output;
+			done;
+			echo "</simplelist>" >> $output;
+		fi;
+		echo "</refsect3>" >> $output;
+	fi;
+	echo "</refsect2>" >> $output;
+done;
+echo "</refsect1>" >> $output
diff --git a/docs/reference/intel-gpu-tools/generate_programs_xml.sh b/docs/reference/intel-gpu-tools/generate_programs_xml.sh
new file mode 100755
index 000000000000..73adc8cc7bfc
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/generate_programs_xml.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+output=$1
+filter=$2
+testlist=$3
+
+echo "<?xml version=\"1.0\"?>" > $output
+echo "<!DOCTYPE refsect1 PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"" >> $output
+echo "               \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $output
+echo "[" >> $output
+echo "  <!ENTITY % local.common.attrib \"xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $output
+echo "  <!ENTITY version SYSTEM \"version.xml\">" >> $output
+echo "]>" >> $output
+echo "<refsect1>" >> $output
+echo "<title>Programs</title>" >> $output
+echo "<informaltable pgwide=\"1\" frame=\"none\"><tgroup cols=\"2\"><tbody>" >> $output
+for test in `cat $testlist | tr ' ' '\n' | grep "^$filter" | sort`; do
+	echo "<row><entry role=\"program_name\">" >> $output;
+	echo "<link linkend=\"$test\">$test</link></entry></row>" >> $output;
+done;
+echo "</tbody></tgroup></informaltable>" >> $output
+echo "</refsect1>" >> $output
diff --git a/docs/reference/intel-gpu-tools/meson.build b/docs/reference/intel-gpu-tools/meson.build
new file mode 100644
index 000000000000..1c009229aae2
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/meson.build
@@ -0,0 +1,80 @@
+gnome = import('gnome')
+
+ignore_headers = [
+	'gen6_render.h',
+	'gen7_media.h',
+	'gen7_render.h',
+	'gen8_media.h',
+	'gen8_render.h',
+	'gpgpu_fill.h',
+	'i830_reg.h',
+	'i915_3d.h',
+	'i915_pciids.h',
+	'i915_reg.h',
+	'igt_edid_template.h',
+	'intel_reg.h',
+	'debug.h',
+	'instdone.h',
+	'media_fill.h',
+	'rendercopy.h',
+	'media_spin.h',
+	'media_fill_gen9.h',
+	'gen9_render.h',
+	'version.h',
+]
+
+test_groups = [
+	'amdgpu',
+	'chamelium',
+	'core',
+	'debugfs',
+	'drm',
+	'drv',
+	'gem',
+	'gen3',
+	'gen7',
+	'gvt',
+	'kms',
+	'meta',
+	'perf',
+	'pm',
+	'prime',
+	'sw_sync',
+	'testdisplay',
+	'tools',
+	'vgem',
+]
+
+gen_description = find_program('generate_description_xml.sh')
+gen_programs = find_program('generate_programs_xml.sh')
+
+test_list_files = []
+
+foreach group : test_groups
+	programs_xml = 'igt_test_programs_' + group + '_programs.xml'
+	custom_target(programs_xml,
+		      output : programs_xml,
+		      build_by_default : true,
+		      command : [ gen_programs, '@OUTPUT@', group, test_list ])
+
+	description_xml = 'igt_test_programs_' + group + '_description.xml'
+	custom_target(description_xml,
+		      output : description_xml,
+		      build_by_default : true,
+		      depends : test_executables,
+		      command : [ gen_description, '@OUTPUT@', group, test_list ])
+endforeach
+
+configure_file(input: 'version.xml.in',
+	       output: 'version.xml',
+	       install: false, configuration: config)
+
+gnome.gtkdoc('intel-gpu-tools',
+	     content_files : ['igt_test_programs.xml'],
+	     dependencies : lib_igt,
+	     install : true,
+	     main_xml : 'intel-gpu-tools-docs.xml',
+	     scan_args : '--rebuild-sections',
+	     mkdb_args : '--output-format=xml',
+	     ignore_headers : ignore_headers,
+	     src_dir : inc_for_gtkdoc)
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
new file mode 100644
index 000000000000..944f28a5615e
--- /dev/null
+++ b/docs/reference/meson.build
@@ -0,0 +1 @@
+subdir('intel-gpu-tools')
diff --git a/meson.build b/meson.build
index 2361866b32d2..e3fb0cd5ed61 100644
--- a/meson.build
+++ b/meson.build
@@ -28,6 +28,8 @@ endforeach
 
 inc = include_directories('include/drm-uapi', 'lib', '.')
 
+inc_for_gtkdoc = include_directories('lib')
+
 config = configuration_data()
 
 libdrm = dependency('libdrm', version : '>=2.4.82')
@@ -139,3 +141,4 @@ if libdrm_intel.found()
 	endif
 endif
 subdir('man')
+subdir('docs')
diff --git a/meson.sh b/meson.sh
index cbf1a9326dbe..ae8e3488d962 100755
--- a/meson.sh
+++ b/meson.sh
@@ -28,7 +28,7 @@ install uninstall:
 	echo "meson install support not yet completed" && false
 
 docs:
-	echo "meson gtkdoc support not yet completed" && false
+	ninja -C build intel-gpu-tools-doc
 
 EOF
 
diff --git a/tests/meson.build b/tests/meson.build
index 9030cf0d1b5e..5555d5886164 100644
--- a/tests/meson.build
+++ b/tests/meson.build
@@ -261,12 +261,14 @@ endif
 
 libexecdir = join_paths(get_option('prefix'), get_option('libexecdir'), 'intel-gpu-tools')
 
+test_executables = []
+
 foreach prog : test_progs
 	link = []
 	if prog == 'perf_pmu'
 		link += lib_igt_perf
 	endif
-	executable(prog, prog + '.c',
+	test_executables += executable(prog, prog + '.c',
 		   dependencies : test_deps,
 		   install_dir : libexecdir,
 		   link_with : link,
@@ -288,6 +290,8 @@ custom_target('testlist',
 	      install : true,
 	      install_dir : pkgdatadir)
 
+test_list = files('test-list.txt')
+
 test_script = find_program('igt_command_line.sh')
 foreach prog : test_progs
 	test('testcase check: ' + prog, test_script,
-- 
2.15.0

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

✓ Fi.CI.BAT: success for series starting with [1/2] lib: avoid < in gtkdoc comments

[Patchwork]

== Series Details ==

Series: series starting with [1/2] lib: avoid < in gtkdoc comments
URL   : https://patchwork.freedesktop.org/series/34609/
State : success

== Summary ==

IGT patchset tested on top of latest successful build
380cc811486ba3fefbe3ebe4761afa7e169dcd3e tests/perf_pmu: Sync invalid-init with i915 changes

with latest DRM-Tip kernel build CI_DRM_3404
c544c3050125 drm-tip: 2017y-11m-29d-08h-19m-47s UTC integration manifest

No testlist changes.

Test debugfs_test:
        Subgroup read_all_entries:
                dmesg-warn -> PASS       (fi-bdw-gvtdvm) fdo#103938 +1
Test gem_ringfill:
        Subgroup basic-default-hang:
                dmesg-warn -> PASS       (fi-pnv-d510) fdo#101600
Test kms_pipe_crc_basic:
        Subgroup read-crc-pipe-b:
                fail       -> PASS       (fi-skl-6700k) fdo#103191 +1
        Subgroup suspend-read-crc-pipe-b:
                incomplete -> PASS       (fi-snb-2520m) fdo#103713

fdo#103938 https://bugs.freedesktop.org/show_bug.cgi?id=103938
fdo#101600 https://bugs.freedesktop.org/show_bug.cgi?id=101600
fdo#103191 https://bugs.freedesktop.org/show_bug.cgi?id=103191
fdo#103713 https://bugs.freedesktop.org/show_bug.cgi?id=103713

fi-bdw-5557u     total:288  pass:267  dwarn:0   dfail:0   fail:0   skip:21  time:442s
fi-bdw-gvtdvm    total:288  pass:264  dwarn:0   dfail:0   fail:0   skip:24  time:446s
fi-blb-e6850     total:288  pass:223  dwarn:1   dfail:0   fail:0   skip:64  time:386s
fi-bsw-n3050     total:288  pass:242  dwarn:0   dfail:0   fail:0   skip:46  time:528s
fi-bwr-2160      total:288  pass:183  dwarn:0   dfail:0   fail:0   skip:105 time:282s
fi-bxt-dsi       total:288  pass:258  dwarn:0   dfail:0   fail:0   skip:30  time:512s
fi-bxt-j4205     total:288  pass:259  dwarn:0   dfail:0   fail:0   skip:29  time:510s
fi-byt-j1900     total:288  pass:253  dwarn:0   dfail:0   fail:0   skip:35  time:489s
fi-byt-n2820     total:288  pass:249  dwarn:0   dfail:0   fail:0   skip:39  time:475s
fi-elk-e7500     total:288  pass:229  dwarn:0   dfail:0   fail:0   skip:59  time:432s
fi-gdg-551       total:288  pass:178  dwarn:1   dfail:0   fail:1   skip:108 time:270s
fi-glk-1         total:288  pass:260  dwarn:0   dfail:0   fail:0   skip:28  time:540s
fi-hsw-4770      total:288  pass:261  dwarn:0   dfail:0   fail:0   skip:27  time:360s
fi-hsw-4770r     total:288  pass:224  dwarn:0   dfail:0   fail:0   skip:64  time:262s
fi-ivb-3520m     total:288  pass:259  dwarn:0   dfail:0   fail:0   skip:29  time:481s
fi-kbl-7500u     total:288  pass:263  dwarn:1   dfail:0   fail:0   skip:24  time:492s
fi-kbl-7560u     total:288  pass:269  dwarn:0   dfail:0   fail:0   skip:19  time:526s
fi-kbl-7567u     total:288  pass:268  dwarn:0   dfail:0   fail:0   skip:20  time:469s
fi-kbl-r         total:288  pass:261  dwarn:0   dfail:0   fail:0   skip:27  time:534s
fi-pnv-d510      total:288  pass:223  dwarn:0   dfail:0   fail:0   skip:65  time:591s
fi-skl-6260u     total:288  pass:268  dwarn:0   dfail:0   fail:0   skip:20  time:451s
fi-skl-6600u     total:288  pass:261  dwarn:0   dfail:0   fail:0   skip:27  time:542s
fi-skl-6700hq    total:288  pass:262  dwarn:0   dfail:0   fail:0   skip:26  time:570s
fi-skl-6700k     total:288  pass:263  dwarn:0   dfail:0   fail:1   skip:24  time:507s
fi-skl-6770hq    total:288  pass:268  dwarn:0   dfail:0   fail:0   skip:20  time:496s
fi-skl-gvtdvm    total:288  pass:265  dwarn:0   dfail:0   fail:0   skip:23  time:451s
fi-snb-2520m     total:288  pass:249  dwarn:0   dfail:0   fail:0   skip:39  time:554s
fi-snb-2600      total:288  pass:248  dwarn:0   dfail:0   fail:0   skip:40  time:418s
Blacklisted hosts:
fi-cfl-s2        total:288  pass:262  dwarn:0   dfail:0   fail:0   skip:26  time:608s
fi-cnl-y         total:288  pass:261  dwarn:0   dfail:0   fail:0   skip:27  time:560s

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_562/
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

✓ Fi.CI.IGT: success for series starting with [1/2] lib: avoid < in gtkdoc comments

[Patchwork]

== Series Details ==

Series: series starting with [1/2] lib: avoid < in gtkdoc comments
URL   : https://patchwork.freedesktop.org/series/34609/
State : success

== Summary ==

Blacklisted hosts:
shard-apl        total:2452 pass:1519 dwarn:28  dfail:15  fail:9   skip:877 time:12292s
shard-hsw        total:2650 pass:1518 dwarn:8   dfail:0   fail:10  skip:1113 time:9009s
shard-kbl        total:2293 pass:1455 dwarn:90  dfail:12  fail:13  skip:715 time:8063s
shard-snb        total:2576 pass:1253 dwarn:16  dfail:4   fail:8   skip:1293 time:6763s

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_562/shards.html
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH i-g-t 1/2] lib: avoid < in gtkdoc comments

[Joonas Lahtinen]

On Wed, 2017-11-29 at 12:17 +0100, Daniel Vetter wrote:
> For reasons entirely not clear to me meson gtkdoc runs in strict
> xml parsing mode, whereas automake gtkdoc doesn't. And gtkdoc itself
> is tooooooooo dense to correctly escape this stuff.
> 
> Paper around this.
> 
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

&lt;foo> looks trippy.

As we're not trying to document HTML stuff, maybe simly <foo> ->
${foo}. I'm pretty sure everyone will be comfortable with that
notation.

Regards, Joonas
-- 
Joonas Lahtinen
Open Source Technology Center
Intel Corporation
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx