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

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Mon, Jul 8, 2024 at 2:43 PM Kent Gibson <warthog618@xxxxxxxxx> 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@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
>
>

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.

Bart