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

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@gmail.com>
---

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

Hi Kent,

kernel test robot noticed the following build warnings:

[auto build test WARNING on linus/master]
[also build test WARNING on v6.4-rc5 next-20230609]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Kent-Gibson/doc-add-configuration-to-generate-doxygen-documentation-on-readthedocs/20230610-100330
base:   linus/master
patch link:    https://lore.kernel.org/r/20230610020148.8973-1-warthog618%40gmail.com
patch subject: [libgpiod][PATCH] doc: add configuration to generate doxygen documentation on readthedocs.
config: powerpc-randconfig-r035-20230610 (https://download.01.org/0day-ci/archive/20230610/202306101327.8CQ451FM-lkp@intel.com/config)
compiler: clang version 16.0.4 (https://github.com/llvm/llvm-project.git ae42196bc493ffe877a7e3dff8be32035dea4d07)
reproduce (this is a W=1 build):
        mkdir -p ~/bin
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # install powerpc cross compiling tool for clang build
        # apt-get install binutils-powerpc-linux-gnu
        git checkout linus/master
        b4 shazam https://lore.kernel.org/r/20230610020148.8973-1-warthog618@gmail.com
        # save the config file
        mkdir build_dir && cp config build_dir/.config
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang ~/bin/make.cross W=1 O=build_dir ARCH=powerpc olddefconfig
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang ~/bin/make.cross W=1 O=build_dir ARCH=powerpc SHELL=/bin/bash

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202306101327.8CQ451FM-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> .readthedocs.yaml: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/.gitignore: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/Makefile: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/run_tags_test.sh: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/tags_test.c: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/.gitignore: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/Makefile: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/config: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/settings: warning: ignored by one of the .gitignore files

Hi Kent,

kernel test robot noticed the following build warnings:

[auto build test WARNING on linus/master]
[also build test WARNING on v6.4-rc5]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Kent-Gibson/doc-add-configuration-to-generate-doxygen-documentation-on-readthedocs/20230610-100330
base:   linus/master
patch link:    https://lore.kernel.org/r/20230610020148.8973-1-warthog618%40gmail.com
patch subject: [libgpiod][PATCH] doc: add configuration to generate doxygen documentation on readthedocs.
config: arm-randconfig-r046-20230608 (https://download.01.org/0day-ci/archive/20230610/202306101333.92BOpai5-lkp@intel.com/config)
compiler: arm-linux-gnueabi-gcc (GCC) 12.3.0
reproduce (this is a W=1 build):
        mkdir -p ~/bin
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        git checkout linus/master
        b4 shazam https://lore.kernel.org/r/20230610020148.8973-1-warthog618@gmail.com
        # save the config file
        mkdir build_dir && cp config build_dir/.config
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-12.3.0 ~/bin/make.cross W=1 O=build_dir ARCH=arm olddefconfig
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-12.3.0 ~/bin/make.cross W=1 O=build_dir ARCH=arm SHELL=/bin/bash

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202306101333.92BOpai5-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> .readthedocs.yaml: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/.gitignore: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/Makefile: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/run_tags_test.sh: warning: ignored by one of the .gitignore files
   tools/testing/selftests/arm64/tags/tags_test.c: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/.gitignore: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/Makefile: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/config: warning: ignored by one of the .gitignore files
   tools/testing/selftests/kvm/settings: warning: ignored by one of the .gitignore files

On Sat, Jun 10, 2023 at 7:43 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> On Sat, Jun 10, 2023 at 01:20:47PM +0800, kernel test robot wrote:
> > Hi Kent,
> >
> > kernel test robot noticed the following build warnings:
> >
>
> Ok, not sure what to make of that - why is the test robot concerned with
> libgpiod patches?
>
> The files in the patch aren't ignored by the .gitignores in the libgpiod
> tree, so it must've applied the patch to the linux tree - which doesn't
> like dot-files. That wont end well either way.
>
> Can we tell the test robot not to try paddling around in the libgpiod
> pool, e.g. ignore patches with the [libgpiod] prefix?
>
> Cheers,
> Kent.

Normally the robot can figure out non-kernel patches. I think this
time it got confused by the commit only adding a new file and tried to
apply it to the kernel?

Anyway, I'm not sure where to report this. Looks like the robot lives
on github, so I'll try opening an issue there.

Bart

On Sat, Jun 10, 2023 at 4:01 AM Kent Gibson <warthog618@gmail.com> 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@gmail.com>
> ---
>
> 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@gmail.com>

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@gmail.com>
> +#
> +# 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@gmail.com>
> +
> +   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/

On Mon, Jun 12, 2023 at 6:40 PM Kent Gibson <warthog618@gmail.com> wrote:
>
> On Mon, Jun 12, 2023 at 06:27:42PM +0200, Bartosz Golaszewski wrote:
> > On Sat, Jun 10, 2023 at 4:01 AM Kent Gibson <warthog618@gmail.com> wrote:
> > >
> > > +# Copyright (C) 2022 Bartosz Golaszewski <bartekgola@gmail.com>
> >
> > 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.
> >
>
> Yeah, this is an old patch prior to that change and I haven't updated
> it - just sent it as is since that is what has been used to generate the
> rtd to date, and you mentioned you wanted to look into updating the
> docs.
>
>
> > 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.
> >
>
> That was the idea.  I thought I had posted it back during v2
> development, but apparently not.
>
> So you want the copyright headers updated?
>

Yes, please.

Bart