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

[Kent Gibson <warthog618@gmail.com>]

On Tue, Jul 09, 2024 at 05:48:33PM +0200, Bartosz Golaszewski wrote:
> On Tue, Jul 9, 2024 at 11:34 AM Kent Gibson <warthog618@gmail.com> 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@gmail.com> 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?
>

It looks to be versions all the way down ;-).

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

I agree - if C and C++ are tied then it is simpler to can keep them
as one. We can always split them later if the need arises.

Ok then, what you are describing is what RTD refers to as subprojects.
The sticking point being RTD expects tags or branches to key off.
To date you've only been tagging and branching core.
Given the need to backport doc patches, branches would be more
appropriate than tags.

Python can be a subproject, so maintenance branches for any revisions
you want to expose would be useful.

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

I think you mean docs.rs? crates.io is the home of rust crates, and
the libgpiod crates are published there ok.  But the docs are built
separately on docs.rs, and that is where the build is failing - as it
can't find a libgpiod library for libgpiod-sys to link to.
So that will need to be built first.

Back to RTD; the RTD Rust page can link to docs.rs - I anticipate that
fixing the docs.rs build would be easier to sort out than working out
how to get Rust doc through Sphinx, and docs.rs needs to be sorted
anyway.

As such, RTD won't need branches for the Rust bindings.

Hopefully that all makes sense.

Cheers,
Kent.