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

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Mon, Feb 10, 2025 at 4:10 PM Vincent Fazio <vfazio@xxxxxxxxxxx> wrote:
>
>
>
> > -----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'
>
>

I worked around it in docs/Makefile.am.

Bart