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

[Kent Gibson <warthog618@gmail.com>]

On Mon, Jul 08, 2024 at 03:50:45PM +0200, Bartosz Golaszewski wrote:
> On Mon, Jul 8, 2024 at 2:43 PM Kent Gibson <warthog618@gmail.com> wrote:
> >
> > On Mon, Jul 08, 2024 at 01:48:11PM +0200, Bartosz Golaszewski wrote:
> > > On Sat, Jul 6, 2024 at 4:55 AM Kent Gibson <warthog618@gmail.com> wrote:
> > > >
> > > > On Fri, Jul 05, 2024 at 09:41:31AM +0200, Bartosz Golaszewski wrote:
> > > > > From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> > > > >
> > > > >
> > > > > On Fri, 05 Jul 2024 10:17:50 +0800, Kent Gibson wrote:
> > > > > > Generating the latest documentation on readthedocs is broken as the
> > > > > > index.html generated by Doxygen is now being overwritten by one
> > > > > > generated by Sphinx.
> > > > > >
> > > > > > Make Sphinx generate a differently named root page that does not
> > > > > > conflict with the index.html generated by Doxygen.
> > > > > >
> > > > > > [...]
> > > > >
> > > > > Applied, thanks!
> > > > >
> > > > > [1/1] doc: fix sphinx config for rtd
> > > > >       commit: 824c1f39347c2ef46919dfc45e8247441b908827
> > > > >
> > > >
> > > > Btw, I ran across this while updating RTD to v2.1 - their default build
> > > > config has changed since I last updated, so that didn't go as smoothly
> > > > as I had anticipated (the plan was to switch the branch the generation
> > > > uses from my fork to your github repo, but now that can wait til v2.2).
> > > >
> > > > I am also looking at reworking the documentation to use Sphinx/Breathe
> > > > to generate the html from the xml that Doxygen generates, and
> > > > incorporting documentation for the Python bindings, but looking is
> > > > about as far as I've gotten so far.
> > >
> > > YES please! We really need this and I've had it on my TODO list for
> > > far too long.
> > >
> >
> > IIRC we last discussed it a couple years ago while working on libgpiod v2,
> > and then it dropped off my radar.
> > I was looking for something I can work on from time to time in small
> > chunks, and it seemed a good fit.
> >
> > My current WIP is here[1].  It is generating C, C++ and Python docs ok.
> > Still need to workout how to handle the Rust bindings.
> > Once I'm satisfied with the outline I'll back fill some additional text to
> > tie it all together.
> >
> > It is currently generated by libgpiod/sphinx/docs.sh, which is a
> > rough approximation of how it will be called on rtd, with the resulting
> > documentation entry point being sphinx/_readthedocs/html/index.html.
> > That is run in a venv with sphinx and sphinx-rtd-theme installed with pip.
> >
> > It is totally independent of the existing doxygen doc generation/make
> > doc, which I didn't want to mess with.
> >
> > Cheers,
> > Kent.
> >
> > [1]https://github.com/warthog618/libgpiod/tree/doc_revamp
> >
> >
>
> 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.

Cheers,
Kent.