mbox series

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

Message ID 20241222-improve-docs-v2-0-9067aa775099@linaro.org
Headers show
Series doc: improvements for ReadTheDocs | expand

Message

Bartosz Golaszewski Dec. 22, 2024, 8:08 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.

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@linaro.org>
---
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@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 -
 .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,