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

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Wed, Jul 10, 2024 at 3:48 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> 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@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?
> >
>
> 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.
>

Neither is a problem really. I can tag older commits alright.

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

I'll create one for the current python release.

Bart

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