02é x/08/2024 12:48, Juraj Linkeš:
> On 1. 8. 2024 17:07, Thomas Monjalon wrote:
> > 01/08/2024 15:03, Juraj Linkeš:
> >> On 30. 7. 2024 15:51, Thomas Monjalon wrote:
> >>> 12/07/2024 10:57, Juraj Linkeš:
> >>>> +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. xFalse,
> 'navigation_depth': -1,
> }
>
> The sidebar configuration is conditional, so we have to pass something
> to indicate dts build. I'll change it so that we look for 'dts' in src
> in call-sphinx-build.py (we're in the dts doc directory, indicating dts
> build) and set the DTS_BUILD env var which we can use in conf.py. I
> didn't find a better way to do this as conf.py doesn't have any
> information about the build itself (and no path that conf.py has access
> to points to anything dts). Here's how it'll look:
>
> if environ.get('DTS_BUILD'):
> path.append(path_join(dirname(dirname(dirname(__file__))), 'dts'))
> # DTS Sidebar config.
> html_theme_options = {
> 'collapse_navigation': False,
> 'navigation_depth': -1, # unlimited depth
> }
OK
> >>>> +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.
> >
>
> I understand and would also prefer that, but it just doesn't work for
> Python. Not all packages are available from the package managers, and
> Python projects should not use system packages as there are frequently
> version mismatches between the system packages and what the project
> needs (the APIs could be different as well as behavior; a problem we've
> seen with Scapy). Poetry is one of the tools that tries to solve this
> well-known Python limitation.
I fully agree for DTS runtime.
I'm expecting the dependencies are more tolerant for DTS doc.
> I've done a quick search of what's available in Ubuntu and two packages
> aren't available, types-PyYAML (which maybe we could do without, I'll
> have to test) and aenum (which is currently needed for the capabilities
> patch; if absolutely necessary, maybe I could find a solution without
> aenum). But even with this we can't be sure that the system package
> versions will work.
We need them all to generate the documentation?
> >>>> +.. 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?
>
> Maybe we could add a script that would check the dependencies. I'll see
> what I can do.
OK thanks
