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

[Kent Gibson <warthog618@xxxxxxxxx>]

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@xxxxxxxxx> wrote:
> >
> > On Fri, Jul 05, 2024 at 09:41:31AM +0200, Bartosz Golaszewski wrote:
> > > From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> > >
> > >
> > > 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