<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Aug 14, 2024 at 11:05 AM Juraj Linkeš <juraj.linkes@pantheon.tech> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">The tool used to generate DTS API docs is Sphinx, which is already in<br>
use in DPDK. The same configuration is used to preserve style with one<br>
DTS-specific configuration (so that the DPDK docs are unchanged) that<br>
modifies how the sidebar displays the content. There's other Sphinx<br>
configuration related to Python docstrings which doesn't affect DPDK doc<br>
build. All new configuration is in a conditional block, applied only<br>
when DTS API docs are built to not interfere with DPDK doc build.<br>
<br>
Sphinx generates the documentation from Python docstrings. The docstring<br>
format is the Google format [0] which requires the sphinx.ext.napoleon<br>
extension. The other extension, sphinx.ext.intersphinx, enables linking<br>
to objects in external documentations, such as the Python documentation.<br>
<br>
There is one requirement for building DTS docs - the same Python version<br>
as DTS or higher, because Sphinx's autodoc extension imports the code.<br>
<br>
The dependencies needed to import the code don't have to be satisfied,<br>
as the autodoc extension allows us to mock the imports. The missing<br>
packages are taken from the DTS pyproject.toml file.<br>
<br>
And finally, the DTS API docs can be accessed from the DPDK API doxygen<br>
page.<br>
<br>
[0] <a href="https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings" rel="noreferrer" target="_blank">https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings</a><br>
<br>
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech><br></blockquote><div><br></div><div>Tested-by: Dean Marx <<a href="mailto:dmarx@iol.unh.edu">dmarx@iol.unh.edu</a>> </div></div></div>