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

[Thomas Monjalon <thomas@monjalon.net>]

16/09/2024 10:51, Juraj Linkeš:
> On 12. 9. 2024 22:09, Thomas Monjalon wrote:
> > 21/08/2024 17:02, Juraj Linkeš:
> >> +    req_deps = _get_dependencies(_DTS_DEP_FILE_PATH)
> >> +    req_deps.pop('python')
> >> +
> >> +    for req_dep, dep_data in (req_deps | _EXTRA_DEPS).items():
> > 
> > Please could you explain somewhere why _EXTRA_DEPS is needed?
> 
> I'll add this comment above the variable:
> # The names of packages used in import statements may be different from 
> distribution package names.
> # We get distribution package names from pyproject.toml.
> # _EXTRA_DEPS adds those import names which don't match their 
> distribution package name.

Good


> > I feel the need for dependencies should be explained in the script.
> 
>  From my point of view, the script gets the dependencies and it's up to 
> the caller how they use the list of dependencies.
> 
> The caller is conf.py and there's a bit of an explanation:
> # Get missing DTS dependencies. Add path to buildtools to find the 
> get_missing_imports function.
> 
> And then:
> # Ignore missing imports from DTS dependencies.
> 
> So basically get the dependencies so we know what to ignore.
> 
> But I could add something to the script if this is not enough.

The unclear part is how it works without these dependencies.


> >> +# initialize common Doxygen configuration
> >> +cdata = configuration_data()
> >> +
> >> +subdir('dts')
> > 
> > Why inserting DTS first before generating DPDK API doc?
> 
> I wanted to put it before subdir_done(). Maybe we could put 
> subdir('dts') in the else branch and also at the end of the meson.build 
> file. That could be better.

Yes


> >> +    # Intersphinx allows linking to external projects, such as Python docs.
> >> +    intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
> > 
> > I'm not sure about the need for this intersphinx.
> 
> It's not stricly needed, but it produces better documentation, with 
> links to Python docs for classes and other things found there.
> 
> For example:
> :class:`~argparse.Action` in a docstring will link to 
> https://docs.python.org/3/library/argparse.html#argparse.Action

If you think it helps, I'm fine.