RE: [PATCH libgpiod v2 0/5] doc: improvements for ReadTheDocs

[Vincent Fazio <vfazio@xxxxxxxxxxx>]

> -----Original Message-----
> From: Bartosz Golaszewski <brgl@xxxxxxxx>
> Sent: Sunday, December 22, 2024 2:08 PM
> To: Vincent Fazio <vfazio@xxxxxxxxxxx>; Kent Gibson
> <warthog618@xxxxxxxxx>; Linus Walleij <linus.walleij@xxxxxxxxxx>; Erik
> Schilling <erik.schilling@xxxxxxxxxx>; Phil Howard <phil@xxxxxxxxxxxxx>;
> Viresh Kumar <viresh.kumar@xxxxxxxxxx>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>; linux-
> gpio@xxxxxxxxxxxxxxx
> Subject: [External] - [PATCH libgpiod v2 0/5] doc: improvements for
> ReadTheDocs
> 
> One thing that this project is missing is nicely looking, accessible and
> automatically updated documentation. I'd like to finally address it and replace
> our static doxygen pages with sphinx docs.
> 
> I spent some time playing with sphinx, doxygen, breathe and exhale. It turned
> out that exhale doesn't support doxygen groups and I really want to have
> them for the core C API to avoid having to manually assign each function to a
> specific module. That means we must use breathe on its own to integrate our
> existing doxygen docs with .rst.
> 
> First four patches in this series address some issues with C++ and python docs
> that became apparent when I started integrating sphinx.
> 
> The final patch contains all the stuff sphinx needs to build us a nice website. If
> the RTD theme is available, then we're using it, otherwise let's fall back to the
> default theme.
> 
> Eventually I'd like to extend the documentation with examples, descriptions of
> gpio-tools and DBus API etc. but first let's agree this is the way forward. For
> now, the docs describe libgpiod, libgpiodcxx and python APIs.
> 
> I allowed myself to publish this branch on RTD for testing purposes.


Is this https://libgpiod.readthedocs.io/en/latest/ ?

These look really good!

There are only a few things that stand out, but I have practically zero experience with sphinx, so don't know if these can be addressed or not:

* Class __init__ functions are resolving Enums back to the base `_ext` values and I don't think we want to publicly reference that private module (see LineSettings).

* Enum __init__ function signatures look raw. I suppose I was expecting something like https://websockets.readthedocs.io/en/stable/reference/sansio/common.html#websockets.protocol.State but maybe that's because we don't use `IntEnum`?

* We're documenting the `LineRequest` constructor. Ideally users don't manually construct `LineRequest` objects. The __init__ docstring says "DON'T USE" for this reason but the class's docstring is being used in the generated docs and does not have this warning.

* Is there a way to generate links to the source code for the classes/methods (the websockets docs do this)?

None of these are huge issues and can be worked out in subsequent patches IMO.

-Vincent