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

[Juraj Linkeš]

On 7. 8. 2024 14:27, Thomas Monjalon wrote:
> 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?
> 

It works the same way. shutil.copyfile (which is used to copy the file) 
follows symlinks, so DTS API gets a copy in its _static dir 
(doc/api/dts/html/_static/css).
I did it this way to preserve the style in case there's something in the 
css file that applies to both DPDK and DTS API docs.

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

Ok, I think putting all of these into the DTS if branch ("if 
environ.get('DTS_BUILD'):") would make sense then.