Re: [libgpiod][PATCH] doc: add configuration to generate doxygen documentation on readthedocs.

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Sat, Mar 5, 2022 at 10:40 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> Having the libgpiod documentation available online would be helpful, so
> add the configuration required to generate the existing doxygen C/C++
> documentation on readthedocs.
>
> Signed-off-by: Kent Gibson <warthog618@xxxxxxxxx>
>
> ---
>
> This is intended to be a minimal change that can be applied to both
> master and v1.6.x and have zero impact on existing builds.
> It has been tested on RTD using the current v1.6.3 release[1].
> The approach used here is to replace any Sphinx documentation generated
> by RTD with the doxygen documentation.
> A subsequent patch for v2 can switch to using Breathe/Sphinx to include
> the documentation for the Python bindings as well.  And relocate the
> Sphinx configuration into the doc directory.
>
> Cheers,
> Kent.
> [1] https://libgpiod.readthedocs.io/en/latest/
>
>  .readthedocs.yaml | 29 ++++++++++++++++++++
>  sphinx/conf.py    | 70 +++++++++++++++++++++++++++++++++++++++++++++++
>  sphinx/index.rst  | 24 ++++++++++++++++
>  3 files changed, 123 insertions(+)
>  create mode 100644 .readthedocs.yaml
>  create mode 100644 sphinx/conf.py
>  create mode 100644 sphinx/index.rst
>
> diff --git a/.readthedocs.yaml b/.readthedocs.yaml
> new file mode 100644
> index 0000000..976496c
> --- /dev/null
> +++ b/.readthedocs.yaml
> @@ -0,0 +1,29 @@
> +# SPDX-License-Identifier: LGPL-2.1-or-later
> +
> +#
> +# This file is part of libgpiod.
> +#
> +# Copyright (C) 2022 Bartosz Golaszewski <bartekgola@xxxxxxxxx>
> +#
> +# Read the Docs configuration file
> +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
> +
> +version: 2
> +
> +build:
> +  os: ubuntu-20.04
> +  tools:
> +    python: "3.9"
> +  # doxygen is available by default, but just in case.
> +  # others are definitely missing.
> +  apt_packages:
> +      - autoconf
> +      - autoconf-archive
> +      - libtool
> +      - m4
> +      - doxygen
> +      - graphviz
> +
> +sphinx:
> +   configuration: sphinx/conf.py
> +
> diff --git a/sphinx/conf.py b/sphinx/conf.py
> new file mode 100644
> index 0000000..7022ff9
> --- /dev/null
> +++ b/sphinx/conf.py
> @@ -0,0 +1,70 @@
> +# SPDX-License-Identifier: LGPL-2.1-or-later
> +
> +#
> +# This file is part of libgpiod.
> +#
> +# Copyright (C) 2022 Bartosz Golaszewski <bartekgola@xxxxxxxxx>
> +#
> +# Configuration file for the Sphinx documentation builder.
> +#
> +# This file only contains a selection of the most common options. For a full
> +# list see the documentation:
> +# https://www.sphinx-doc.org/en/master/usage/configuration.html
> +
> +import subprocess
> +
> +subprocess.run('cd .. ; ./autogen.sh ; make doc', shell=True)
> +
> +# -- Path setup --------------------------------------------------------------
> +
> +# If extensions (or modules to document with autodoc) are in another directory,
> +# add these directories to sys.path here. If the directory is relative to the
> +# documentation root, use os.path.abspath to make it absolute, like shown here.
> +#
> +# import os
> +# import sys
> +# sys.path.insert(0, os.path.abspath('.'))
> +
> +
> +# -- Project information -----------------------------------------------------
> +
> +project = 'libgpiod'
> +copyright = '2022, Bartosz Golaszewski'
> +author = 'Bartosz Golaszewski'
> +
> +# The full version, including alpha/beta/rc tags
> +release = subprocess.run(
> +            ['git', 'describe', '--dirty'],
> +            capture_output=True).stdout.decode().strip()
> +
> +# -- General configuration ---------------------------------------------------
> +
> +# Add any Sphinx extension module names here, as strings. They can be
> +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> +# ones.
> +extensions = [
> +]
> +
> +# Add any paths that contain templates here, relative to this directory.
> +templates_path = []
> +
> +# List of patterns, relative to source directory, that match files and
> +# directories to ignore when looking for source files.
> +# This pattern also affects html_static_path and html_extra_path.
> +exclude_patterns = []
> +
> +
> +# -- Options for HTML output -------------------------------------------------
> +
> +# The theme to use for HTML and HTML Help pages.  See the documentation for
> +# a list of builtin themes.
> +#
> +html_theme = 'alabaster'
> +
> +# Add any paths that contain custom static files (such as style sheets) here,
> +# relative to this directory. They are copied after the builtin static files,
> +# so a file named "default.css" will overwrite the builtin "default.css".
> +html_static_path = []
> +
> +html_extra_path = ['../doc/html']
> +
> diff --git a/sphinx/index.rst b/sphinx/index.rst
> new file mode 100644
> index 0000000..e38fad7
> --- /dev/null
> +++ b/sphinx/index.rst
> @@ -0,0 +1,24 @@
> +.. SPDX-License-Identifier: LGPL-2.1-or-later
> +
> +..
> +   This file is part of libgpiod.
> +
> +   Copyright (C) 2022 Bartosz Golaszewski <bartekgola@xxxxxxxxx>

All looks good to me except that Copyright should be yours here, not mine. :)

Bart

> +
> +   libgpiod documentation master file.
> +
> +Welcome to libgpiod's documentation!
> +====================================
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :caption: Contents:
> +
> +
> +
> +Indices and tables
> +==================
> +
> +* :ref:`genindex`
> +* :ref:`modindex`
> +* :ref:`search`
> --
> 2.35.1
>