Re: [igt-dev] [PATCH i-g-t v4 1/8] meson: build Xe test documentation

[Juha-Pekka Heikkila <juhapekka.heikkila@gmail.com>]

On 30.3.2023 8.20, Mauro Carvalho Chehab wrote:
> On Tue, 28 Mar 2023 20:56:34 +0300
> Juha-Pekka Heikkila <juhapekka.heikkila@gmail.com> wrote:
> 
>> On 24.3.2023 15.31, Kamil Konieczny wrote:
>>> On 2023-03-22 at 09:28:19 +0100, Mauro Carvalho Chehab wrote:
>>>> From: Mauro Carvalho Chehab <mchehab@kernel.org>
>>>>
>>>> Add the remaining changes at meson for it to build Xe documentation.
>>>>
>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>>>
>>> Reviewed-by: Kamil Konieczny <kamil.konieczny@linux.intel.com>
>>
>> Because of this patch building igt started to fail for me like this:
>>
>> ---
>> Configuration error:
>> There is a programable error in your configuration file:
>>
>> Traceback (most recent call last):
>>     File "/usr/lib/python2.7/dist-packages/sphinx/config.py", line 157,
>> in __init__
>>       execfile_(filename, config)
>>     File "/usr/lib/python2.7/dist-packages/sphinx/util/pycompat.py", line
>> 150, in execfile_
>>       exec_(code, _globals)
>>     File "/usr/lib/python2.7/dist-packages/six.py", line 709, in exec_
>>       exec("""exec _code_ in _globs_, _locs_""")
>>     File "<string>", line 1, in <module>
>>     File "conf.py", line 6, in <module>
>>       from shutil import which
>> ImportError: cannot import name which
>> ---
>>
>> Cleaning out old build and rebuild also fail. This is on ubuntu 18.04
> 
> I added at IGT upstream two patches, one getting rid of shutil dependency
> and the another one making the conf.py file compatible with Ubuntu 18.04:
> 
> 	https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/commit/c6585fd1c070c2ad299f6aaa6fa5438535c002b9
> 	https://gitlab.freedesktop.org/drm/igt-gpu-tools/-/commit/f91dc09b9e9f5794705259e6947e47ae788a0a5d
> 
> I tested only with python 3, but just ran vermin[1]. It seems it should
> run with any Python version.
> 
> [1] https://pypi.org/project/vermin/
> 
> Please test.

Works for me. Thx for fixing.

/Juha-Pekka

>>>    
>>>> ---
>>>>    docs/meson.build           |  1 +
>>>>    docs/testplan/conf.py      | 42 +++++++++++++++++++++++++++++++++++++
>>>>    docs/testplan/testplan.css |  7 +++++++
>>>>    meson_options.txt          |  8 +++++++
>>>>    scripts/gen_rst_index      | 43 ++++++++++++++++++++++++++++++++++++++
>>>>    scripts/meson.build        |  3 +++
>>>>    6 files changed, 104 insertions(+)
>>>>    create mode 100644 docs/testplan/conf.py
>>>>    create mode 100644 docs/testplan/testplan.css
>>>>    create mode 100755 scripts/gen_rst_index
>>>>
>>>> diff --git a/docs/meson.build b/docs/meson.build
>>>> index ead14c4015d9..01edf64f04a8 100644
>>>> --- a/docs/meson.build
>>>> +++ b/docs/meson.build
>>>> @@ -1 +1,2 @@
>>>>    subdir('reference')
>>>> +subdir('testplan')
>>>> diff --git a/docs/testplan/conf.py b/docs/testplan/conf.py
>>>> new file mode 100644
>>>> index 000000000000..cfb866cc7a15
>>>> --- /dev/null
>>>> +++ b/docs/testplan/conf.py
>>>> @@ -0,0 +1,42 @@
>>>> +# -*- coding: utf-8 -*-
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR MIT)
>>>> +
>>>> +import sys
>>>> +import os
>>>> +from shutil import which
>>>> +
>>>> +extensions = []
>>>> +
>>>> +if which('rst2pdf'):
>>>> +    extensions.append('rst2pdf.pdfbuilder')
>>>> +
>>>> +source_suffix = '.rst'
>>>> +master_doc = 'index'
>>>> +
>>>> +project = 'IGT Test Tools'
>>>> +copyright = 'Intel'
>>>> +author = 'IGT developers'
>>>> +language = 'en'
>>>> +
>>>> +exclude_patterns = []
>>>> +todo_include_todos = False
>>>> +
>>>> +html_theme = "nature"
>>>> +
>>>> +html_css_files = []
>>>> +html_static_path = ['.']
>>>> +html_copy_source = False
>>>> +
>>>> +html_use_smartypants = False
>>>> +html_sidebars = { '**': ['searchbox.html', 'localtoc.html']}
>>>> +htmlhelp_basename = 'IGT'
>>>> +
>>>> +html_theme_options = {
>>>> +    "body_max_width": "1520px",
>>>> +    "sidebarwidth": "400px",
>>>> +}
>>>> +
>>>> +# rst2pdf
>>>> +pdf_documents = [
>>>> +    ('index', u'xe_tests', u'IGT Xe Tests', u'IGT authors'),
>>>> +]
>>>> diff --git a/docs/testplan/testplan.css b/docs/testplan/testplan.css
>>>> new file mode 100644
>>>> index 000000000000..8aa7b7105c19
>>>> --- /dev/null
>>>> +++ b/docs/testplan/testplan.css
>>>> @@ -0,0 +1,7 @@
>>>> +@import url(html4css1.css);
>>>> +
>>>> +.literal {
>>>> +	background: lightgrey;
>>>> +        color: darkblue;
>>>> +        font-size: 14px;
>>>> +}
>>>> diff --git a/meson_options.txt b/meson_options.txt
>>>> index d978813b4feb..d4e373d6cfc4 100644
>>>> --- a/meson_options.txt
>>>> +++ b/meson_options.txt
>>>> @@ -20,6 +20,14 @@ option('man',
>>>>           type : 'feature',
>>>>           description : 'Build man pages')
>>>>    
>>>> +option('testplan',
>>>> +       type : 'feature',
>>>> +       description : 'Build testplan documentation pages in ReST and html')
>>>> +
>>>> +option('sphinx',
>>>> +       type : 'feature',
>>>> +       description : 'Build testplan documentation using Sphinx')
>>>> +
>>>>    option('docs',
>>>>           type : 'feature',
>>>>           description : 'Build documentation')
>>>> diff --git a/scripts/gen_rst_index b/scripts/gen_rst_index
>>>> new file mode 100755
>>>> index 000000000000..34955a35a443
>>>> --- /dev/null
>>>> +++ b/scripts/gen_rst_index
>>>> @@ -0,0 +1,43 @@
>>>> +#!/bin/bash -e
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR MIT)
>>>> +
>>>> +## Copyright (C) 2023    Intel Corporation                 ##
>>>> +## Author: Mauro Carvalho Chehab <mchehab@kernel.org>      ##
>>>> +##                                                         ##
>>>> +## Small script to produce a ReST index file               ##
>>>> +
>>>> +if [ $# -lt 3 ]; then
>>>> +	echo 'Usage: $0: <title> <files> <dest_dir>' >&2
>>>> +	exit 1
>>>> +fi
>>>> +
>>>> +title=$1
>>>> +shift
>>>> +
>>>> +args=( "$@" )
>>>> +
>>>> +dest_dir=${args[${#args[@]}-1]}
>>>> +unset args[${#args[@]}-1]
>>>> +
>>>> +if [ ! -d $dest_dir ]; then
>>>> +	echo "Error: $dest_dir directory doesn't exist" >&2
>>>> +	exit 1
>>>> +fi
>>>> +
>>>> +dest_file="$dest_dir/index.rst"
>>>> +
>>>> +echo $title > "$dest_file"
>>>> +len=${#title}
>>>> +for i in $(seq 1 $len); do
>>>> +	echo -n "=" >> "$dest_file"
>>>> +done
>>>> +echo >> "$dest_file"
>>>> +echo >> "$dest_file"
>>>> +
>>>> +echo ".. toctree::" >> "$dest_file"
>>>> +echo "   :maxdepth: 1" >> "$dest_file"
>>>> +echo >> "$dest_file"
>>>> +
>>>> +for i in "${!args[@]}"; do
>>>> +	echo "   ${args[$i]}" >> "$dest_file"
>>>> +done
>>>> diff --git a/scripts/meson.build b/scripts/meson.build
>>>> index 342972e66078..ce12aa02e946 100644
>>>> --- a/scripts/meson.build
>>>> +++ b/scripts/meson.build
>>>> @@ -11,3 +11,6 @@ if build_tests
>>>>    		install_data(prog, install_dir : bindir, install_mode : 'r-xr-xr-x')
>>>>    	endforeach
>>>>    endif
>>>> +
>>>> +igt_doc_script = find_program('igt_doc.py')
>>>> +gen_rst_index = find_program('gen_rst_index')
>>>> -- 
>>>> 2.39.2
>>>>   
>>