[v8,4/5] doc: guides and API meson improvements
Checks
Commit Message
The Sphinx script argument parsing improvement gives us more
flexibility going forward, such as the ability to add non-positional
arguments.
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>
Reviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Tested-by: Luca Vizzarro <luca.vizzarro@arm.com>
Tested-by: Nicholas Pratte <npratte@iol.unh.edu>
---
buildtools/call-sphinx-build.py | 28 +++++++++++++++++++---------
doc/api/meson.build | 7 ++++---
doc/guides/conf.py | 6 ++----
3 files changed, 25 insertions(+), 16 deletions(-)
Comments
12/07/2024 10:57, Juraj Linkeš:
> The Sphinx script argument parsing improvement gives us more
> flexibility going forward, such as the ability to add non-positional
> arguments.
You should describe what is changed and why.
> -release = environ.setdefault('DPDK_VERSION', "None")
> -version = release
> +version = environ.setdefault('DPDK_VERSION', "None")
I'm quite sure "release" was set for a reason.
Did it change over time with recent Sphinx?
On 30. 7. 2024 15:28, Thomas Monjalon wrote:
> 12/07/2024 10:57, Juraj Linkeš:
>> The Sphinx script argument parsing improvement gives us more
>> flexibility going forward, such as the ability to add non-positional
>> arguments.
>
> You should describe what is changed and why.
>
The Sphinx script argument parsing improvement gives us more
flexibility going forward, such as the ability to add non-positional
arguments. What is currently missing is the ability to define an
argument with default value, which is added here.
The other change just cleans up the code a bit, replacing the path:
dpdk_build_root/doc/api
with
meson.current_build_dir(),
which is the same, as it's called in the above dir that was previously
hardcoded.
>
>> -release = environ.setdefault('DPDK_VERSION', "None")
>> -version = release
>> +version = environ.setdefault('DPDK_VERSION', "None")
>
> I'm quite sure "release" was set for a reason.
> Did it change over time with recent Sphinx?
>
>
I looked at the docs and it didn't. I didn't realize this was a Sphinx
setting. I'll revert this.
@@ -3,31 +3,41 @@
# Copyright(c) 2019 Intel Corporation
#
+import argparse
import sys
import os
from os.path import join
from subprocess import run
-# assign parameters to variables
-(sphinx, version, src, dst, *extra_args) = sys.argv[1:]
+parser = argparse.ArgumentParser()
+parser.add_argument('sphinx')
+parser.add_argument('version')
+parser.add_argument('src')
+parser.add_argument('dst')
+args, extra_args = parser.parse_known_args()
# set the version in environment for sphinx to pick up
-os.environ['DPDK_VERSION'] = version
+os.environ['DPDK_VERSION'] = args.version
-sphinx_cmd = [sphinx] + extra_args
+sphinx_cmd = [args.sphinx] + extra_args
# find all the files sphinx will process so we can write them as dependencies
srcfiles = []
-for root, dirs, files in os.walk(src):
+for root, dirs, files in os.walk(args.src):
srcfiles.extend([join(root, f) for f in files])
+if not os.path.exists(args.dst):
+ os.makedirs(args.dst)
+
# run sphinx, putting the html output in a "html" directory
-with open(join(dst, 'sphinx_html.out'), 'w') as out:
- process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],
- stdout=out)
+with open(join(args.dst, 'sphinx_html.out'), 'w') as out:
+ process = run(
+ sphinx_cmd + ['-b', 'html', args.src, join(args.dst, 'html')],
+ stdout=out
+ )
# create a gcc format .d file giving all the dependencies of this doc build
-with open(join(dst, '.html.d'), 'w') as d:
+with open(join(args.dst, '.html.d'), 'w') as d:
d.write('html: ' + ' '.join(srcfiles) + '\n')
sys.exit(process.returncode)
@@ -1,6 +1,7 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+doc_api_build_dir = meson.current_build_dir()
doxygen = find_program('doxygen', required: get_option('enable_docs'))
if not doxygen.found()
@@ -32,10 +33,10 @@ example = custom_target('examples.dox',
# set up common Doxygen configuration
cdata = configuration_data()
cdata.set('VERSION', meson.project_version())
-cdata.set('API_EXAMPLES', join_paths(dpdk_build_root, 'doc', 'api', 'examples.dox'))
-cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
+cdata.set('API_EXAMPLES', join_paths(doc_api_build_dir, 'examples.dox'))
+cdata.set('OUTPUT', doc_api_build_dir)
cdata.set('TOPDIR', dpdk_source_root)
-cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
+cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, doc_api_build_dir]))
cdata.set('WARN_AS_ERROR', 'NO')
if get_option('werror')
cdata.set('WARN_AS_ERROR', 'YES')
@@ -7,8 +7,7 @@
from sphinx import __version__ as sphinx_version
from os import listdir
from os import environ
-from os.path import basename
-from os.path import dirname
+from os.path import basename, dirname
from os.path import join as path_join
from sys import argv, stderr
@@ -35,8 +34,7 @@
html_show_copyright = False
highlight_language = 'none'
-release = environ.setdefault('DPDK_VERSION', "None")
-version = release
+version = environ.setdefault('DPDK_VERSION', "None")
master_doc = 'index'