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

[Thomas Monjalon <thomas@monjalon.net>]

07/08/2024 14:03, Juraj Linkeš:
> On 7. 8. 2024 12:41, Thomas Monjalon wrote:
> > 06/08/2024 17:19, Juraj Linkeš:
> > [...]
> >> +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).

OK

> >> --- /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.

The file is copied in _static dir of sphinx guides.
How does it work for DTS API?


> >> +# 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.

My concern is to allow generating DPDK doc without DTS,
without the new extra dependencies.