[PATCH v15 5/5] dts: add API doc generation

[Juraj Linkeš]

On 7. 8. 2024 12:41, Thomas Monjalon wrote:
> 06/08/2024 17:19, Juraj Linkeš:
>> +"""Utilities for DTS dependencies.
>> +
>> +The module can be used as an executable script,
>> +which verifies that the running Python version meets the version requirement of DTS.
>> +The script returns the standard exit codes in this mode (0 is success, 1 is failure).
> 
> Is it returning the list of dependencies for generating doc?
> 

It's not worded right. When run as a script, it exits with the standard 
exit codes, it doesn't return anything.
The function below is for returning the list of depedencies.

>> +
>> +The module also contains a function, get_missing_imports,
>> +which looks for runtime and doc generation dependencies in the DTS pyproject.toml file
>> +a returns a list of module names used in an import statement that are missing.
> 
> typo? a -> and

Ack.

> 
> [...]
>> +get_dts_deps = py3 + files('get-dts-deps.py')
> 
> deps for runtime or doc?
> may be good to specify in the name
> 

It's getting both, actually.
Now that I think about it, we don't need to get the docs dependencies, 
as we check for Sphinx elsewhere. We really only need to get the runtime 
dependencies and mock what's missing (that is add those to the 
autodoc_mock_imports config option).

I think it makes sense to change the script and rename it to 
get-dts-runtime-deps.py (and the variable).

> 
>> --- /dev/null
>> +++ b/doc/api/dts/custom.css
>> @@ -0,0 +1 @@
>> +../../guides/custom.css
>> \ No newline at end of file
> 
> Is it a link? Why?
> 

call-sphinx-build.py copies the custom.css file. I added a link to 
preserve the look.

>> +htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk', 'dts')
>> +dts_api_html = custom_target('dts_api_html',
>> +        output: 'html',
>> +        command: [sphinx_wrapper, sphinx, meson.project_version(),
>> +            meson.current_source_dir(), meson.current_build_dir(), extra_sphinx_args],
>> +        build_by_default: get_option('enable_docs'),
>> +        install: get_option('enable_docs'),
>> +        install_dir: htmldir)
> 
> When custom.css is copied?
> 

I'm not sure what you're asking here. The call-sphinx-build.py copies it 
during the build and it's also copied during the install phase.

> 
> 
>> +# Napoleon enables the Google format of Python doscstrings, used in DTS.
>> +# Intersphinx allows linking to external projects, such as Python docs, also used in DTS.
>> +extensions = ['sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
> 
> What happens if napoleon and intersphinx are not available
> when building basic DPDK doc without DTS?
> 
> 

napoleon was added in version 1.3 and intersphinx in 0.5, so I didn't 
think of testing that.

I tried adding a non-existent extension to the list and got this error:
Extension error:
Could not import extension sphinx.ext.foo (exception: No module named 
'sphinx.ext.foo')

I could add version checks for each of the extensions.