RE: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings

[Vincent Fazio <vfazio@xxxxxxxxxxx>]

> -----Original Message-----
> From: Bartosz Golaszewski <brgl@xxxxxxxx>
> Sent: Thursday, February 6, 2025 6:22 AM
> To: Vincent Fazio <vfazio@xxxxxxxxxxx>; Kent Gibson
> <warthog618@xxxxxxxxx>; Linus Walleij <linus.walleij@xxxxxxxxxx>; Erik
> Schilling <erik.schilling@xxxxxxxxxx>; Phil Howard <phil@xxxxxxxxxxxxx>;
> Viresh Kumar <viresh.kumar@xxxxxxxxxx>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>; linux-
> gpio@xxxxxxxxxxxxxxx
> Subject: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for
> GLib bindings
> 
> From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> 
> The GObject docs are generated with gi-docgen and there doesn't seem to be
> an easy way of converting them to sphinx. Let's put the GLib docs statically
> into the sphinx output and reference them from the bindings chapter.
> 
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> ---
>  .readthedocs.yaml |  9 ++++++++-
>  docs/Makefile.am  |  1 +
>  docs/bindings.rst |  1 +
>  docs/conf.py      | 38 ++++++++++++++++++++++++++++++++++++++
>  docs/glib_api.rst | 23 +++++++++++++++++++++++
>  5 files changed, 71 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/conf.py b/docs/conf.py index 3d0209a..33fc89f 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -62,8 +62,46 @@ def autodoc_skip_init(app, what, name, obj,
> would_skip, options):
>      return would_skip
> 
> 
> +# We need to know where to put docs generated by gi-docgen but
> +app.outdir is # only set once the builder is initialized. Let's delay
> +running gi-docgen # until we're notified.
> +def make_glib_docs(app):
> +    # For some reason on RTD we're in the docs/ directory while during a local
> +    # build, we're still in the top source directory.
> +    prefix = "../" if os.getenv("READTHEDOCS") == "True" else ""

Building via `sphinx-build ./docs/ docs/sphinx-output` seems to work ok but building via `make docs` does not, maybe due to `make -C docs docs ` changing directory and requiring the prefix be present?

Maybe we should always use the "../" prefix and expect callers from the top directory to: `pushd docs; sphinx-build . ./sphinx-output; popd`

(venv) root@9935cce25ae1:/work# make docs > /dev/null
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force -I m4
autoreconf: configure.ac: tracing
autoreconf: running: libtoolize --copy --force
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /usr/bin/autoconf --force
autoreconf: running: /usr/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
configure.ac:54: installing 'autostuff/compile'
configure.ac:40: installing 'autostuff/missing'
bindings/cxx/Makefile.am: installing 'autostuff/depcomp'
autoreconf: Leaving directory '.'
/work/venv/lib/python3.12/site-packages/breathe/project.py:116: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  self._default_build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
usage: gi-docgen generate [-h] [-q] [--fatal-warnings]
                          [--add-include-path INCLUDE_PATHS] [-C FILE]
                          [--dry-run] [--templates-dir TEMPLATES_DIR]
                          [--content-dir CONTENT_DIRS] [--theme-name THEME_NAME]
                          [--output-dir OUTPUT_DIR] [--no-namespace-dir]
                          [--section SECTIONS]
                          GIRFILE
gi-docgen generate: error: argument GIRFILE: can't open 'bindings/glib/Gpiodglib-1.0.gir': [Errno 2] No such file or directory: 'bindings/glib/Gpiodglib-1.0.gir'