| Message ID | 20250206-improve-docs-v3-13-2065191fff6f@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | doc: improvements for ReadTheDocs | expand |
> -----Original Message----- > From: Bartosz Golaszewski <brgl@bgdev.pl> > Sent: Thursday, February 6, 2025 6:22 AM > To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson > <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik > Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>; > Viresh Kumar <viresh.kumar@linaro.org> > Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux- > gpio@vger.kernel.org > Subject: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for > GLib bindings > > From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org> > > 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@linaro.org> > --- > .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'
On Mon, Feb 10, 2025 at 4:10 PM Vincent Fazio <vfazio@xes-inc.com> wrote: > > > > > -----Original Message----- > > From: Bartosz Golaszewski <brgl@bgdev.pl> > > Sent: Thursday, February 6, 2025 6:22 AM > > To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson > > <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik > > Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>; > > Viresh Kumar <viresh.kumar@linaro.org> > > Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux- > > gpio@vger.kernel.org > > Subject: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for > > GLib bindings > > > > From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org> > > > > 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@linaro.org> > > --- > > .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
diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 510b5c1..97086fa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,13 +11,20 @@ version: 2 build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: python: "3.12" apt_packages: + - autoconf + - autoconf-archive # doxygen is available by default, but just in case. - doxygen + - gi-docgen + - gir1.2-glib-2.0-dev + - gobject-introspection - graphviz + - libtool + - pkg-config sphinx: configuration: docs/conf.py diff --git a/docs/Makefile.am b/docs/Makefile.am index dd3e6ac..ef9ebf2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -32,6 +32,7 @@ DOCS_DEPS = \ cpp_request_config.rst \ Doxyfile \ index.rst \ + glib_api.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/bindings.rst b/docs/bindings.rst index ed7ec69..73f1262 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -19,3 +19,4 @@ C library. cpp_api python_api + glib_api 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 "" + + subprocess.run( + [ + "gi-docgen", + "generate", + "--config", + f"{prefix}bindings/glib/gi-docgen.toml", + f"{prefix}bindings/glib/Gpiodglib-1.0.gir", + "--output-dir", + f"{app.outdir}", + ], + check=True, + ) + + def setup(app): app.connect("autodoc-skip-member", autodoc_skip_init) + app.connect("builder-inited", make_glib_docs) subprocess.run(["doxygen", "Doxyfile"]) + +cwd = os.getcwd() +os.chdir("..") +subprocess.run(["autoreconf", "-ifv"], check=True) +subprocess.run( + [ + "./configure", + "--enable-tools", + "--enable-bindings-glib", + "--enable-introspection", + ], + check=True, +) +subprocess.run(["make", "-j"], check=True) +os.chdir(cwd) diff --git a/docs/glib_api.rst b/docs/glib_api.rst new file mode 100644 index 0000000..307f5f7 --- /dev/null +++ b/docs/glib_api.rst @@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org> + +.. + This file is part of libgpiod. + + libgpiod GObject API documentation + +libgpiod GObject bindings API +============================= + +**GObject bindings** for libgpiod provide a high-level, object-oriented +interface to interact with GPIO (General Purpose Input/Output) lines on Linux +systems. These bindings leverage the **GObject framework**, commonly used in +GNOME and GTK+ applications, to wrap the lower-level C API of libgpiod. + +.. warning:: + The documentation for GObject bindings is generated using gi-docgen and + cannot be easily integrated with sphinx documentation. Please navigate to + a separate section dedicated exclusively to the GLib part of the API. + +`Navigate to GObject bindings documentation <Gpiodglib-1.0/index.html>`_