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

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Sat, Jun 10, 2023 at 4:01 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> Having the libgpiod documentation available online would be helpful, so
> add the configuration required to generate the existing docygen C/C++
> documentation on readthedocs.
>
> Signed-off-by: Kent Gibson <warthog618@xxxxxxxxx>
> ---
>
> Speaking of readthedocs - it looks like the config to generate the
> documentation there hasn't made it's way into master, so here it is.
>
> It might be due for an update, as it is over a year old now, but this is
> what is currently deployed.
>
> Cheers,
> Kent.
>
>  .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>

I would stick with regular SPDX-FileCopyrightText line that we use
everywhere else and - while I understand that I maintain the project -
this file is authored by you so it's only right to have your copyright
here.

> +#
> +# 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>
> +
> +   libgpiod documentation master file.
> +
> +Welcome to libgpiod's documentation!
> +====================================
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :caption: Contents:
> +
> +
> +
> +Indices and tables
> +==================
> +
> +* :ref:`genindex`
> +* :ref:`modindex`
> +* :ref:`search`
> --
> 2.40.1
>

This works well with sphinx-build, thank you for doing that. I'm
actually looking into using the breathe[1] and exhale[2] extensions
for sphinx for translating doxygen into nice sphinx docs. This is a
good fundament to build upon.

Bart

[1] https://breathe.readthedocs.io/en/latest/
[2] https://exhale.readthedocs.io/en/latest/