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

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Mon, Dec 23, 2024 at 3:28 PM Vincent Fazio <vfazio@xxxxxxxxxxx> wrote:
>
>
>
> > -----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/ ?
>

Yes, I keep the WiP public on readthedocs. It's changed quite a bit
recently, please (re)take a look.

> 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:
>

Yeah, I'm not an expert either so I want these docs to at least be good enough.

> * 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`?
>

These should be fixed now?

> * 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.
>

I added a tweak to include __init__() and its docstring in .rst.

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

Ugh, I don't know, I spent a couple minutes looking for answers and
none are straightforward so I'll skip this one for now.

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

Thanks for the review!

Bart