| Message ID | 20240705021750.43197-1-warthog618@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | [libgpiod] doc: fix sphinx config for rtd | expand |
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
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
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
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
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.
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
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.
+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
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.
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
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.
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. >
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
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%)