mbox series

[libgpiod,0/5] doc: improvements for ReadTheDocs

Message ID 20241220-improve-docs-v1-0-799b86991dec@linaro.org
Headers show
Series doc: improvements for ReadTheDocs | expand

Message

Bartosz Golaszewski Dec. 20, 2024, 4:46 p.m. UTC 
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,