Re: [libgpiod][PATCH] doc: fix sphinx config for rtd

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Tue, Jul 9, 2024 at 11:34 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> On Mon, Jul 08, 2024 at 11:29:46PM +0800, Kent Gibson wrote:
> > On Mon, Jul 08, 2024 at 05:19:41PM +0200, Bartosz Golaszewski wrote:
> > > On Mon, Jul 8, 2024 at 5:15 PM Kent Gibson <warthog618@xxxxxxxxx> wrote:
> > > >
> > > > >
> > > > > Would we be able to then have a proper RTD website with a version
> > > > > selector etc? That would be awesome and it's one of the last big
> > > > > missing bits for libgpiod to be more available to beginners.
> > > > >
> > > >
> > > > Going forwards for sure.
> > > >
> > > > Going backwards is more problematic, particularly if changes to the code
> > > > docs are required to get them to render properly.  I've got a few of
> > > > those lined up already.  Should be able to work out something to patch
> > > > older versions, but haven't put much thought into it at this point.
> > > >
>
> And the python build has changed too.
>
> > > > Cheers,
> > > > Kent.
> > >
> > > I guess going forward is enough.
> > >
> >
> > I'm not ruling out supporting older revisions - but it will require
> > additional work.  Longer term I would like to see all 2.x and even 1.6.
> > But the immediate goal is 2.1 and/or 2.2, depending when it lands.
> >
>
> But of course I have to look into this now anyway, as it impacts how the
> build is structured...
>
> I was thinking the maintenance branches could have the sphinx doc
> generation backported, and the versions exposed on RTD would correspond
> to the maintenance branches. Those could be updated and rolled out
> piecemeal. So I'm thinking that is quite doable.
>
> Then I recall that the bindings each have their own version, e.g. python
> is now at 2.2.0, and rust is 0.2.2, while core is at 2.1.2.
> And I'm not even sure what version C++ is at (does that track core??).
> How do you want to handle that?  The simplest would be for the RTD version
> to correspond to the core/maintenance branch, as I had intended.
> The corresponding binding version could be displayed on the page for the
> binding.
>
> Would that work for you?

What level of versioning clusterf*ck are we on anyway?

C++ bindings track the C API version. Rust and Python are entirely separate now.

For docs: Ideally we should have separate pages for each part of the
project: core C library, C++ and Python (there are no Doxygen comments
here, only pydoc) with their own version selectors. C and C++ could
potentially live together though. Python bindings should probably get
their own stable branches at some point but there was no need so far.

For rust: I think the docs belong on Rust.rs. Viresh, Erik: Is this
something you plan to do eventually?

Bart