[PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs

[Bartosz Golaszewski <brgl@xxxxxxxx>]

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.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
---
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/20241222-improve-docs-v2-0-9067aa775099@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 (16):
      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: 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                                 |  22 +-
 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_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                           |  43 ++++
 docs/building.rst                           |  74 ++++++
 docs/conf.py                                | 146 +++++++++++
 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                |  12 +
 docs/python_line_settings.rst               |  12 +
 docs/python_misc.rst                        |  13 +
 docs/requirements.txt                       |   5 +
 docs/testing.rst                            |  46 ++++
 include/gpiod.h                             |  36 ---
 man/Makefile.am                             |  72 +++++-
 sphinx/conf.py                              |  68 -----
 sphinx/contents.rst                         |  24 --
 93 files changed, 1790 insertions(+), 855 deletions(-)
---
base-commit: 5486f1f0ffa419bcbb25288b0157c8e2ab643403
change-id: 20241216-improve-docs-19ed36687963

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>