Re: [PATCH libgpiod 5/5] doc: use sphinx in conjunction with doxygen

["Erik Schilling" <erik.schilling@xxxxxxxxxx>]

On Fri Dec 20, 2024 at 5:46 PM CET, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
>
> Integrate the API documentation generated with doxygen for the core C
> API and C++ bindings into sphinx using breathe. Integrate python docs
> with sphinx using autodoc and the import mock feature which allows us to
> avoid having to build the C extension.
>
> Update configure.ac to check for sphinx-build in addition to doxygen and
> make the main Makefile trigger a sphinx build on `make doc` (although
> the docs can also be generated without starting the build system by
> running: `sphinx-build ./doc/ doc/sphinx-output`).
>
> Create a tree of .rst documents with branches for libgpiod, libgpiodcxx
> and python APIs.
>
> Move the introduction text from the main header into the relevant .rst
> file.
>
> Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where
> all the documentation now lives.
>
> Update .gitignore where needed.
>
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> ---
>  .gitignore                    |   2 -
>  Doxyfile.in                   | 105 ------------------------------------------
>  Makefile.am                   |  54 ++++++++++++++++++++--
>  README                        |  12 ++---
>  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 ----------
>  49 files changed, 733 insertions(+), 249 deletions(-)

Tested-by: Erik Schilling <erik.schilling@xxxxxxxxxx>

> diff --git a/README b/README
> index 80ad939..8d8fe79 100644
> --- a/README
> +++ b/README
> @@ -333,14 +333,12 @@ bindings use the standard tests module layout and the #[test] attribute.
>  DOCUMENTATION
>  -------------
>  
> -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