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

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

[Kent Gibson]

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.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 sphinx/conf.py                     | 2 ++
 sphinx/{index.rst => contents.rst} | 0
 2 files changed, 2 insertions(+)
 rename sphinx/{index.rst => contents.rst} (100%)

diff --git a/sphinx/conf.py b/sphinx/conf.py
index 51ae3e9..043dc79 100644
--- a/sphinx/conf.py
+++ b/sphinx/conf.py
@@ -53,6 +53,8 @@ exclude_patterns = []
 
 # -- Options for HTML output -------------------------------------------------
 
+root_doc = 'contents'
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
diff --git a/sphinx/index.rst b/sphinx/contents.rst
similarity index 100%
rename from sphinx/index.rst
rename to sphinx/contents.rst
-- 
2.39.2

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

[Bartosz Golaszewski]

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

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

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

[Kent Gibson]

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.

Not sure what to do about the Rust bindings.  I was assuming I could
just link to docs.rs, but the build there[1] is broken.
Can we fix that?

Cheers,
Kent.

[1] https://docs.rs/crate/libgpiod/latest

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

[Bartosz Golaszewski]

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.

>
> Not sure what to do about the Rust bindings.  I was assuming I could
> just link to docs.rs, but the build there[1] is broken.
> Can we fix that?
>

I don't know. Viresh?

Bart

> Cheers,
> Kent.
>
> [1] https://docs.rs/crate/libgpiod/latest

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

[Kent Gibson]

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

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

[Bartosz Golaszewski]

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.

Bart

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

[Kent Gibson]

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.

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

[Bartosz Golaszewski]

On Mon, Jul 8, 2024 at 5:15 PM Kent Gibson <warthog618@gmail.com> wrote:
>
> 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.

I guess going forward is enough.

Bart

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

[Kent Gibson]

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

Cheers,
Kent.

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

[Kent Gibson]

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?

Cheers,
Kent.

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

[Bartosz Golaszewski]

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?

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.

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

Bart

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

[Kent Gibson]

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.

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

[Bartosz Golaszewski]

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

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

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

[Viresh Kumar]

+Erik,

On 08-07-24, 13:48, 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.
> 
> >
> > Not sure what to do about the Rust bindings.  I was assuming I could
> > just link to docs.rs, but the build there[1] is broken.
> > Can we fix that?
> >
> 
> I don't know. Viresh?

Erik, since you did the whole pkg manager thing (where it seems to be
failing right now), can you take a look at this please ?

> > [1] https://docs.rs/crate/libgpiod/latest

-- 
viresh