| Message ID | 20241220-improve-docs-v1-0-799b86991dec@linaro.org |
|---|---|
| Headers | show |
| Series | doc: improvements for ReadTheDocs | expand |
On Thu, Jan 2, 2025 at 6:08 PM Erik Schilling <erik.schilling@linaro.org> wrote: > > On Fri Dec 20, 2024 at 5:46 PM CET, Bartosz Golaszewski wrote: > > From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org> > > > > > > -All API symbols exposed by the core C API and C++ bindings are documented with > > -doxygen markup blocks. Doxygen documentation can be generated by executing > > -'make doc' given that the doxygen executable is available in the system. > > +The project uses sphinx to automatically generate the documentation. The system > > +needs to provide doxygen and sphinx-build programs. With those in place, the > > +build can be invoked with 'make doc'. This generates documentation for the core > > +C API as well as C++ and python bindings. > > I also lacked the `breathe` package. Maybe worth mentioning here? > > - Erik There's a v2 on the list and it has a requirements.txt. Bart
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. Once this is merged, the idea is to publish it on RTD for the master branch and 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@linaro.org> --- 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 - Doxyfile.in | 105 ---------------------------- Makefile.am | 54 ++++++++++++-- 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 ++- doc/.gitignore | 5 ++ doc/Doxyfile | 12 ++++ doc/conf.py | 63 +++++++++++++++++ doc/core_api.rst | 58 +++++++++++++++ doc/core_chip_info.rst | 11 +++ doc/core_chips.rst | 11 +++ doc/core_edge_event.rst | 11 +++ doc/core_line_config.rst | 11 +++ doc/core_line_defs.rst | 11 +++ doc/core_line_info.rst | 11 +++ doc/core_line_request.rst | 11 +++ doc/core_line_settings.rst | 11 +++ doc/core_line_watch.rst | 11 +++ doc/core_misc.rst | 11 +++ doc/core_request_config.rst | 11 +++ doc/cpp_api.rst | 33 +++++++++ doc/cpp_chip.rst | 12 ++++ doc/cpp_chip_info.rst | 12 ++++ doc/cpp_edge_event.rst | 12 ++++ doc/cpp_edge_event_buffer.rst | 12 ++++ doc/cpp_exceptions.rst | 18 +++++ doc/cpp_info_event.rst | 12 ++++ doc/cpp_line.rst | 24 +++++++ doc/cpp_line_config.rst | 12 ++++ doc/cpp_line_info.rst | 12 ++++ doc/cpp_line_request.rst | 15 ++++ doc/cpp_line_settings.rst | 12 ++++ doc/cpp_misc.rst | 16 +++++ doc/cpp_request_config.rst | 12 ++++ doc/index.rst | 28 ++++++++ doc/python_api.rst | 31 ++++++++ doc/python_chip.rst | 12 ++++ doc/python_chip_info.rst | 12 ++++ doc/python_edge_event.rst | 12 ++++ doc/python_exceptions.rst | 17 +++++ doc/python_info_event.rst | 12 ++++ doc/python_line.rst | 27 +++++++ doc/python_line_info.rst | 12 ++++ doc/python_line_request.rst | 12 ++++ doc/python_line_settings.rst | 12 ++++ doc/python_misc.rst | 13 ++++ include/gpiod.h | 36 ---------- sphinx/conf.py | 68 ------------------ sphinx/contents.rst | 24 ------- 73 files changed, 809 insertions(+), 395 deletions(-) --- base-commit: 38adbae195555fae2b9d9e2a37c9507af1114757 change-id: 20241216-improve-docs-19ed36687963 Best regards,