doc: improvements for ReadTheDocs
Get series with b4
b4 am [email protected] change-id 20241216-improve-docs-19ed36687963Versions newest first
- v4 Latest17 patches 1 replyIn review
- v316 patches 5 repliesSuperseded
- v25 patches 0 repliesSuperseded
Earlier versions · 1
| Version | Posted | Patches | Replies | Status |
|---|---|---|---|---|
| v1 | 5 patches | 2 replies | Superseded |
Changes in v4 from the cover letter
- remove unconditional docs for __init__() in the python section, use :class-doc-from: both instead for LineRequest
- fix make docs failure with GObject introspection not being found
- fix make clean for sphinx and doxygen output
- fix commit message typos
- fix whitespace errors
- Link to v3: https://lore.kernel.org/r/[email protected]
Patches in v4 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/17 | build: set PACKAGE_URLconfigure.ac | +2 | 0 replies | |
| 2/17 | bindings: cxx: doc: remove the gpiod_cxx doxygen groupbindings/ bindings/ bindings/ +13 more | +0 | 0 replies | |
| 3/17 | bindings: python: doc: update the docstring for gpiod.request_lines()bindings/ | +12 | 0 replies | |
| 4/17 | bindings: python: doc: make code examples appear as such in sphinxbindings/ | +2 | 0 replies | |
| 5/17 | bindings: python: doc: describe undocumented membersbindings/ bindings/ bindings/ +3 more | +62 | 0 replies | |
| 6/17 | bindings: gpiod: reword the docstring for LineRequest.__init__()bindings/ | +2 | 0 replies | |
| 7/17 | bindings: glib: add the configuration file for gi-docgenbindings/ bindings/ bindings/ +1 more | +15 | 0 replies | |
| 8/17 | dbus: daemon: add a more detailed description to help textdbus/ | +9 | 0 replies | |
| 9/17 | dbus: client: tweak help textdbus/ | +1 | 0 replies | |
| 10/17 | dbus: improve comments in API xmldbus/ | +52 | 0 replies | |
| 11/17 | doc: create man entries for gpio-manager and gpiocliMakefile.am man/ | +67 | 0 replies | |
| 12/17 | doc: provide sphinx docs for the core C API and C++ bindings.gitignore .readthedocs.yaml Doxyfile.in +39 more | +591 | 0 replies | |
| 13/17 | doc: add documentation for python bindingsdocs/ docs/ docs/ +11 more | +193 | 0 replies | |
| 14/17 | doc: add documentation for GLib bindings.readthedocs.yaml docs/ docs/ +2 more | +74 | 0 replies | |
| 15/17 | doc: add documentation for gpio-tools.readthedocs.yaml configure.ac docs/ +4 more | +78 | 0 replies | |
| 16/17 | doc: add documentation for D-Bus API, daemon and command-line client.readthedocs.yaml docs/ docs/ +5 more | +105 | 0 replies | |
| 17/17 | doc: move README contents to sphinx docsREADME README.md docs/ +11 more | +551 | 0 replies |
Reviews trailers per patch
1 of 17 patches has a Reviewed-by or Acked-by.
| Patch | Vincent Fazio |
|---|---|
| 1/17 | |
| 2/17 | |
| 3/17 | R-b |
| 4/17 | |
| 5/17 | |
| 6/17 | |
| 7/17 | |
| 8/17 | |
| 9/17 | |
| 10/17 | |
| 11/17 | |
| 12/17 | |
| 13/17 | |
| 14/17 | |
| 15/17 | |
| 16/17 | |
| 17/17 |
Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.
Cover letter [PATCH libgpiod v4 00/17] doc: improvements for ReadTheDocs
One thing that this project is missing is nicely looking, accessible and automatically updated documentation. I'd like to finally address it and replace our static doxygen pages with sphinx docs.
I spent some time playing with sphinx, doxygen, breathe and exhale. It turned out that exhale doesn't support doxygen groups and I really want to have them for the core C API to avoid having to manually assign each function to a specific module. That means we must use breathe on its own to integrate our existing doxygen docs with .rst.
First 10 preparatory patches address existing issues in code documentation. Patches 11-15 add sphinx docs for all project sections and last patch moves most README contents into sphinx as well.
I allowed myself to publish this branch on RTD for testing purposes.
Once this is merged, I'l backport these changes to the v2.2.x branch so that the documentation for the most recent release can become available online too.
---
Changes in v4:
- remove unconditional docs for __init__() in the python section, use :class-doc-from: both instead for LineRequest
- fix make docs failure with GObject introspection not being found
- fix make clean for sphinx and doxygen output
- fix commit message typos
- fix whitespace errors
- Link to v3: https://lore.kernel.org/r/[email protected]
Changes in v3:
- make the commits more fine-grained: add a separate commit for each new documentation section
- set the PACKAGE_URL in configure.ac
- add GLib docs
- add gpio-tools docs
- generate man pages for D-Bus programs
- add docs for D-Bus API and utilities
- reduce the top toc tree depth to 1
- change license of .rst files to CC-BY-SA-4.0
- move most of the README contents into sphinx docs
- many other minor tweaks
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- update .readthedocs.yaml
- add requirements.txt in order for rtd to install breathe
- mv doc docs
- a couple minor improvements
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Bartosz Golaszewski (17):
build: set PACKAGE_URL
bindings: cxx: doc: remove the gpiod_cxx doxygen group
bindings: python: doc: update the docstring for gpiod.request_lines()
bindings: python: doc: make code examples appear as such in sphinx
bindings: python: doc: describe undocumented members
bindings: gpiod: reword the docstring for LineRequest.__init__()
bindings: glib: add the configuration file for gi-docgen
dbus: daemon: add a more detailed description to help text
dbus: client: tweak help text
dbus: improve comments in API xml
doc: create man entries for gpio-manager and gpiocli
doc: provide sphinx docs for the core C API and C++ bindings
doc: add documentation for python bindings
doc: add documentation for GLib bindings
doc: add documentation for gpio-tools
doc: add documentation for D-Bus API, daemon and command-line client
doc: move README contents to sphinx docs
.gitignore | 2 - .readthedocs.yaml | 25 +- Doxyfile.in | 105 -------- Makefile.am | 24 +- README | 386 ---------------------------- README.md | 11 + bindings/cxx/gpiod.hpp | 6 - bindings/cxx/gpiodcxx/chip-info.hpp | 9 - bindings/cxx/gpiodcxx/chip.hpp | 9 - bindings/cxx/gpiodcxx/edge-event-buffer.hpp | 9 - bindings/cxx/gpiodcxx/edge-event.hpp | 9 - bindings/cxx/gpiodcxx/exception.hpp | 9 - bindings/cxx/gpiodcxx/info-event.hpp | 9 - bindings/cxx/gpiodcxx/line-config.hpp | 9 - bindings/cxx/gpiodcxx/line-info.hpp | 9 - bindings/cxx/gpiodcxx/line-request.hpp | 9 - bindings/cxx/gpiodcxx/line-settings.hpp | 9 - bindings/cxx/gpiodcxx/line.hpp | 9 - bindings/cxx/gpiodcxx/misc.hpp | 9 - bindings/cxx/gpiodcxx/request-builder.hpp | 9 - bindings/cxx/gpiodcxx/request-config.hpp | 9 - bindings/cxx/gpiodcxx/timestamp.hpp | 9 - bindings/glib/.gitignore | 1 + bindings/glib/Makefile.am | 6 +- bindings/glib/gi-docgen.toml.in | 9 + bindings/python/gpiod/__init__.py | 15 +- bindings/python/gpiod/chip.py | 4 +- bindings/python/gpiod/chip_info.py | 5 + bindings/python/gpiod/edge_event.py | 9 + bindings/python/gpiod/info_event.py | 8 + bindings/python/gpiod/line.py | 20 ++ bindings/python/gpiod/line_info.py | 12 + bindings/python/gpiod/line_request.py | 6 +- bindings/python/gpiod/line_settings.py | 8 + configure.ac | 33 ++- dbus/client/gpiocli.c | 2 +- dbus/lib/io.gpiod1.xml | 98 +++---- dbus/manager/gpio-manager.c | 9 + docs/.gitignore | 19 ++ docs/Doxyfile | 12 + docs/Makefile.am | 61 +++++ docs/bindings.rst | 27 ++ docs/building.rst | 74 ++++++ docs/conf.py | 137 ++++++++++ docs/contributing.rst | 45 ++++ docs/core_api.rst | 62 +++++ docs/core_chip_info.rst | 11 + docs/core_chips.rst | 11 + docs/core_edge_event.rst | 11 + docs/core_line_config.rst | 11 + docs/core_line_defs.rst | 11 + docs/core_line_info.rst | 11 + docs/core_line_request.rst | 11 + docs/core_line_settings.rst | 11 + docs/core_line_watch.rst | 11 + docs/core_misc.rst | 11 + docs/core_request_config.rst | 11 + docs/cpp_api.rst | 37 +++ docs/cpp_chip.rst | 12 + docs/cpp_chip_info.rst | 12 + docs/cpp_edge_event.rst | 12 + docs/cpp_edge_event_buffer.rst | 12 + docs/cpp_exceptions.rst | 18 ++ docs/cpp_info_event.rst | 12 + docs/cpp_line.rst | 24 ++ docs/cpp_line_config.rst | 12 + docs/cpp_line_info.rst | 12 + docs/cpp_line_request.rst | 15 ++ docs/cpp_line_settings.rst | 12 + docs/cpp_misc.rst | 16 ++ docs/cpp_request_config.rst | 12 + docs/dbus.rst | 37 +++ docs/dbus_api.rst | 23 ++ docs/glib_api.rst | 26 ++ docs/gpio_tools.rst | 241 +++++++++++++++++ docs/gpiocli_top.rst | 110 ++++++++ docs/index.rst | 43 ++++ docs/python_api.rst | 41 +++ docs/python_chip.rst | 12 + docs/python_chip_info.rst | 12 + docs/python_edge_event.rst | 12 + docs/python_exceptions.rst | 17 ++ docs/python_info_event.rst | 12 + docs/python_line.rst | 27 ++ docs/python_line_info.rst | 12 + docs/python_line_request.rst | 13 + docs/python_line_settings.rst | 12 + docs/python_misc.rst | 13 + docs/requirements.txt | 5 + docs/rust_api.rst | 23 ++ docs/testing.rst | 46 ++++ include/gpiod.h | 36 --- man/Makefile.am | 72 +++++- sphinx/conf.py | 68 ----- sphinx/contents.rst | 24 -- 95 files changed, 1793 insertions(+), 859 deletions(-)
---
base-commit: 5486f1f0ffa419bcbb25288b0157c8e2ab643403
change-id: 20241216-improve-docs-19ed36687963
Best regards,
Signature · 1 line
Bartosz Golaszewski <[email protected]>