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

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

[Kent Gibson]

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

---

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

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

[Bartosz Golaszewski]

On Sat, Mar 5, 2022 at 10:40 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 doxygen C/C++
> documentation on readthedocs.
>
> Signed-off-by: Kent Gibson <warthog618@gmail.com>
>
> ---
>
> 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@gmail.com>
> +#
> +# 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>

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
>

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

[Kent Gibson]

On Mon, Mar 07, 2022 at 10:16:49AM +0100, Bartosz Golaszewski wrote:
> On Sat, Mar 5, 2022 at 10:40 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 doxygen C/C++
> > documentation on readthedocs.
> >
> > Signed-off-by: Kent Gibson <warthog618@gmail.com>
> >

[snip]

> > --- /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>
> 
> All looks good to me except that Copyright should be yours here, not mine. :)
> 

Seemed simpler to me to keep it under the one umbrella, so happy to
transfer any and all copyrights to you.

Cheers,
Kent.

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

[Bartosz Golaszewski]

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

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

[Kent Gibson]

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?

Cheers,
Kent.

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

[Bartosz Golaszewski]

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/

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

[Philip Li]

On Mon, Jun 12, 2023 at 02:58:28PM +0200, Bartosz Golaszewski wrote:
> 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?

Sorry for the false positive. Yes, this is the case, the patch was successfully
applied and wrongly considered as kernel patch. We will fix the logic in next
few days to avoid such problem.

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

Thanks, yes, github https://github.com/intel/lkp-tests could be used to report
any issue related to the bot. Or you can drop mail to lkp@intel.com, that we
monitor the mail tightly.

> 
> Bart
> 

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

[Bartosz Golaszewski]

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

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

[Kent Gibson]

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.

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

[kernel test robot]

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

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[kernel test robot]

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

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[Kent Gibson]

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>
+#
+# 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