Skip to contentSkip to conversation

doc: fix sphinx config for rtd

PATCH Applied Kent Gibson 3 participants 14 messages Jul 5, 2024 – Jul 10, 2024 GPIO

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: fix sphinx config for rtd

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.

---
 sphinx/conf.py                     | 2 ++
 sphinx/{index.rst => contents.rst} | 0
 2 files changed, 2 insertions(+)
 rename sphinx/{index.rst => contents.rst} (100%)
sphinx/conf.py +2 -0
index 51ae3e9..043dc79 100644
@@ -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.
 #
sphinx/contents.rst renamed from sphinx/index.rst +0 -0
similarity index 100%
rename from sphinx/index.rst
rename to sphinx/contents.rst
Signature · 1 line
2.39.2
#1 lore raw

From: Bartosz Golaszewski <[email protected]>

Quoted 8 lines · 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.

[...]

Applied, thanks!

[1/1] doc: fix sphinx config for rtd

      commit: 824c1f39347c2ef46919dfc45e8247441b908827

Best regards,

Signature · 1 line
Bartosz Golaszewski <[email protected]>
#2 lore raw
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

#3 lore raw
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 4 lines

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.

Quoted 5 lines

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

Quoted 4 lines

Cheers,
Kent.

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

#4 lore raw
Quoted 27 lines · Bartosz Golaszewski
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 8 lines
Quoted 4 lines

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

#5 lore raw
Quoted 53 lines · Kent Gibson
Quoted 27 lines · Bartosz Golaszewski
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 8 lines
Quoted 4 lines

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.

Quoted 9 lines

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

#6 lore raw
Quoted 60 lines · Bartosz Golaszewski
Quoted 59 lines · Kent Gibson
Quoted 27 lines · Bartosz Golaszewski
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 8 lines
Quoted 4 lines

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.

Quoted 8 lines
Quoted 3 lines

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

#7 lore raw
Quoted 73 lines · Kent Gibson
Quoted 60 lines · Bartosz Golaszewski
Quoted 59 lines · Kent Gibson
Quoted 27 lines · Bartosz Golaszewski
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 8 lines
Quoted 4 lines

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.

Quoted 8 lines
Quoted 3 lines

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

Quoted 7 lines

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

#8 lore raw
Quoted 15 lines · Bartosz Golaszewski
Quoted 14 lines · Kent Gibson
Quoted 6 lines

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.

Quoted 5 lines
Quoted 2 lines

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.

#9 lore raw
Quoted 9 lines · Kent Gibson
Quoted 8 lines · Bartosz Golaszewski
Quoted 7 lines · Kent Gibson
Quoted 6 lines

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.

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

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.

Quoted 10 lines
Quoted 5 lines
Quoted 2 lines

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.

#10 lore raw
Quoted 48 lines · Kent Gibson
Quoted 9 lines · Kent Gibson
Quoted 8 lines · Bartosz Golaszewski
Quoted 7 lines · Kent Gibson
Quoted 6 lines

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.

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

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.

Quoted 10 lines
Quoted 5 lines
Quoted 2 lines

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.

Quoted 1 line

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

#11 lore raw
Quoted 49 lines · Bartosz Golaszewski
Quoted 48 lines · Kent Gibson
Quoted 9 lines · Kent Gibson
Quoted 8 lines · Bartosz Golaszewski
Quoted 7 lines · Kent Gibson
Quoted 6 lines

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.

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

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.

Quoted 10 lines
Quoted 5 lines
Quoted 2 lines

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.

Quoted 4 lines
Quoted 1 line

Would that work for you?

What level of versioning clusterf*ck are we on anyway?

It looks to be versions all the way down ;-).

Quoted 8 lines

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.

Quoted 3 lines

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.

#12 lore raw
Quoted 67 lines · Kent Gibson
Quoted 49 lines · Bartosz Golaszewski
Quoted 48 lines · Kent Gibson
Quoted 9 lines · Kent Gibson
Quoted 8 lines · Bartosz Golaszewski
Quoted 7 lines · Kent Gibson
Quoted 6 lines

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.

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

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.

Quoted 10 lines
Quoted 5 lines
Quoted 2 lines

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.

Quoted 4 lines
Quoted 1 line

Would that work for you?

What level of versioning clusterf*ck are we on anyway?

It looks to be versions all the way down ;-).

Quoted 8 lines

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.

Quoted 9 lines

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.

Quoted 3 lines

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

Quoted 22 lines
Quoted 3 lines

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.

#13 lore raw
In reply to Bartosz Golaszewski

+Erik,

Quoted 36 lines · Bartosz Golaszewski
Quoted 26 lines · Kent Gibson
Quoted 11 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Quoted 7 lines · 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.

Quoted 7 lines
Quoted 1 line

[...]

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

Quoted 4 lines

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.

Quoted 1 line
Quoted 6 lines
Quoted 4 lines

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 ?

Quoted 1 line
Quoted 1 line

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

Signature · 1 line
viresh