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

[Vincent Fazio <vfazio@xxxxxxxxxxx>]

> -----Original Message-----
> From: Bartosz Golaszewski <brgl@xxxxxxxx>
> Sent: Friday, January 10, 2025 9:58 AM
> To: Vincent Fazio <vfazio@xxxxxxxxxxx>
> Cc: Kent Gibson <warthog618@xxxxxxxxx>; Linus Walleij
> <linus.walleij@xxxxxxxxxx>; Erik Schilling <erik.schilling@xxxxxxxxxx>; Phil
> Howard <phil@xxxxxxxxxxxxx>; Viresh Kumar <viresh.kumar@xxxxxxxxxx>;
> Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>; linux-
> gpio@xxxxxxxxxxxxxxx
> Subject: [External] - Re: [PATCH libgpiod v2 0/5] doc: improvements for
> ReadTheDocs
> 
> On Mon, Dec 23, 2024 at 3:28 PM Vincent Fazio <vfazio@xxxxxxxxxxx> wrote:
> >
> >
> > 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.

I certainly think these are good enough for now.

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

I think these are good, we can always revisit

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

Seems like this affected all classes, but at least the warning is there now which is the important bit.

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

Agreed, I think we can follow up on this later.

I think it's done via https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html

You'll see websockets has this defined:
https://github.com/python-websockets/websockets/blob/main/docs/conf.py#L102

It's definitely a convenience thing, not a requirement IMO.

-Vincent