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 four patches in this series address some issues with C++ and python docs that became apparent when I started integrating sphinx. The final patch contains all the stuff sphinx needs to build us a nice website. If the RTD theme is available, then we're using it, otherwise let's fall back to the default theme. Eventually I'd like to extend the documentation with examples, descriptions of gpio-tools and DBus API etc. but first let's agree this is the way forward. For now, the docs describe libgpiod, libgpiodcxx and python APIs. 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. Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx> --- 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/20241220-improve-docs-v1-0-799b86991dec@xxxxxxxxxx --- Bartosz Golaszewski (5): 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 doc: use sphinx in conjunction with doxygen .gitignore | 2 - .readthedocs.yaml | 17 +++-- Doxyfile.in | 105 ---------------------------- Makefile.am | 57 +++++++++++++-- README | 12 ++-- 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/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_settings.py | 8 +++ configure.ac | 8 ++- docs/.gitignore | 5 ++ docs/Doxyfile | 12 ++++ docs/conf.py | 63 +++++++++++++++++ docs/core_api.rst | 58 +++++++++++++++ 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 | 33 +++++++++ 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/index.rst | 28 ++++++++ docs/python_api.rst | 31 ++++++++ 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 | 12 ++++ docs/python_line_settings.rst | 12 ++++ docs/python_misc.rst | 13 ++++ docs/requirements.txt | 5 ++ include/gpiod.h | 36 ---------- sphinx/conf.py | 68 ------------------ sphinx/contents.rst | 24 ------- 75 files changed, 824 insertions(+), 405 deletions(-) --- base-commit: 38adbae195555fae2b9d9e2a37c9507af1114757 change-id: 20241216-improve-docs-19ed36687963 Best regards, -- Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
[PATCH libgpiod v2 0/5] doc: improvements for ReadTheDocs
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
- Subject: [PATCH libgpiod v2 0/5] doc: improvements for ReadTheDocs
- From: Bartosz Golaszewski <brgl@xxxxxxxx>
- Date: Sun, 22 Dec 2024 21:08:05 +0100
- Follow-Ups:
- [PATCH libgpiod v2 5/5] doc: use sphinx in conjunction with doxygen
- From: Bartosz Golaszewski
- [PATCH libgpiod v2 4/5] bindings: python: doc: describe undocumented members
- From: Bartosz Golaszewski
- [PATCH libgpiod v2 2/5] bindings: python: doc: update the docstring for gpiod.request_lines()
- From: Bartosz Golaszewski
- [PATCH libgpiod v2 1/5] bindings: cxx: doc: remove the gpiod_cxx doxygen group
- From: Bartosz Golaszewski
- [PATCH libgpiod v2 3/5] bindings: python: doc: make code examples appear as such in sphinx
- From: Bartosz Golaszewski
- [PATCH libgpiod v2 5/5] doc: use sphinx in conjunction with doxygen
- Prev by Date: Re: [PATCH 04/38] dt-bindings: pinctrl: Add rk3562 pinctrl support
- Next by Date: [PATCH libgpiod v2 3/5] bindings: python: doc: make code examples appear as such in sphinx
- Previous by thread: [brgl:gpio/for-next] BUILD SUCCESS c9ec045fa8053820573efbaa70137d0857e444db
- Next by thread: [PATCH libgpiod v2 3/5] bindings: python: doc: make code examples appear as such in sphinx
- Index(es):
 |