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

[Juraj Linkeš]

On 16. 9. 2024 14:48, Thomas Monjalon wrote:
> 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
> 

Ack.

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

It's a bit unclear to me as well. The docs [0] don't say much and the 
only thing I found is that object paths from third party libraries are a 
bit different:
without dependencies: fabric.Connection
with dependencies: fabric.connection.Connection

Everything else seems to be the same. Do we want to document this and if 
so, where would be the best place? In the script or conf.py?

[0] 
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

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

Ok, I'll make the change.

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

Absolutely, it'll make the docs easier to use.

>