01/08/2024 15:03, Juraj Linkeš:
> On 30. 7. 2024 15:51, Thomas Monjalon wrote:
> > 12/07/2024 10:57, Juraj Linkeš:
> >> The tool used to generate DTS API docs is Sphinx, which is already in
> >> use in DPDK. The same configuration is used to preserve style with one
> >> DTS-specific configuration (so that the DPDK docs are unchanged) that
> >> modifies how the sidebar displays the content.
> >
> > What is changed in the sidebar?
> >
>
> These are the two changes:
> html_theme_options = {
> 'collapse_navigation': False,
> 'navigation_depth': -1,
> }
>
> The first allows you to explore the structure without needing to enter
> any specific section - it puts the + at each section so everything is
> expandable.
> The second just means that each section can be fully expanded (there's
> no limit).
OK interesting, you may add a comment # unlimited depth
> >> +# A local reference must be relative to the main index.html page
> >> +# The path below can't be taken from the DTS meson file as that would
> >> +# require recursive subdir traversal (doc, dts, then doc again)
> >
> > This comment is really obscure.
>
> I guess it is. I just wanted to explain that there's not way to do this
> without spelling out the path this way. At least I didn't find a way.
> Should I remove the comment or reword it?
May be removed I think.
> >> +cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html',
> >> 'index.html'))
> >
> > Oh I think I get it:
> > - DTS_API_MAIN_PAGE is the Meson variable
> > - dts_api_main_page is the Doxygen variable
> >
>
> Yes, this is a way to make it work. Maybe there's something else (I'm
> not that familiar with Doxygen), but from what I can tell, there wasn't
> a command line option that would set a variable (passing the path form
> Meson to Doxygen) and nothing else I found worked.
>
> Is this solution ok? If we want to explore something else, is there
> someone with more experience with Doxygen who could help?
Yes it's OK like that.
> >> +dts_root = environ.get('DTS_ROOT')
> >
> > Why does it need to be passed as an environment variable?
> > Isn't it a fixed absolute path?
>
> The path to DTS needs to be passed in some way (and added to sys.path)
> so that Sphinx knows where the sources are in order to import them.
>
> Do you want us to not pass the path, but just hardcode it here? I didn't
> really think about that, maybe that could work.
I think hardcode is better here.
> >> +To build DTS API docs, install the dependencies with Poetry, then enter
> >> its shell:
> >
> > I don't plan to use Poetry on my machine.
> > Can we simply describe the dependencies even if the versions are not
> > specified?
>
> The reason we don't list the dependencies anywhere is that doing it with
> Poetry is much easier (and a bit safer, as Poetry is going to install
> tested versions).
>
> But I can add references to the two relevant sections of
> dts/pyproject.toml which contain the dependencies with a note that they
> can be installed with pip (and I guess that would be another
> dependency), but at that point it's that not much different than using
> Poetry.
I want to use my system package manager.
I am from this old school thinking we should have a single package manager in a
system.
> >> +.. code-block:: console
> >> +
> >> + poetry install --no-root --with docs
> >> + poetry shell
> >> +
> >> +The documentation is built using the standard DPDK build system.
> >> +After executing the meson command and entering Poetry's shell, build the
> >> documentation with:
> >> +
> >> +.. code-block:: console
> >> +
> >> + ninja -C build dts-doc
> >
> > Don't we rely on the Meson option "enable_docs"?
>
> I had a discussion about this with Bruce, but I can't find it anywhere,
> so here's what I remember:
> 1. We didn't want to tie the dts api doc build to dpdk doc build because
> of the dependencies.
Sure
But we could just skip if dependencies are not met?
> 2. There's a way to build docs without the enable_docs option (running
> ninja with the target), which is what we added for dts. This doesn't tie
> the dts api doc build to the dpdk doc build.
Yes
> 3. We had an "enable_dts_docs" Meson option in the past (to keep it
> separate from dpdk doc build), but decided to drop it. My memory is hazy
> on this, but I think it was, again, because of the additional steps
> needed to bring up the dependency (poetry shell) - at that point,
> supporting just the ninja build way is sufficient. Bruce may shed more
> light on this.
> >> + Make sure to fix any Sphinx warnings when adding or updating
> >> docstrings,
> >> + and also run the ``devtools/dts-check-format.sh`` script and address
> >> any issues it finds.
> >
> > It looks like something to write in the contributing guide.
> >
>
> I could add it there, where is the right place? In patches.rst, section
> "Checking the Patches"?
Yes
