doc: add configuration to generate doxygen documentation on readthedocs.

Hi Kent,

kernel test robot noticed the following build warnings:

Quoted 4 lines · kernel test robot

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.

Quoted 17 lines · Kent Gibson

Quoted 4 lines · kernel test robot

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?

Quoted 2 lines

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

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 <[email protected]>

---

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

.readthedocs.yaml new file +0 -0

new file mode 100644
index 0000000..976496c

.readthedocs.yaml new file +23 -0

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

sphinx/conf.py new file +70 -0

new file mode 100644
index 0000000..7022ff9
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+
+#
+# This file is part of libgpiod.
+#
+# Copyright (C) 2022 Bartosz Golaszewski <[email protected]>
+#
+# 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']
+

sphinx/index.rst new file +24 -1

new file mode 100644
index 0000000..e38fad7
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+..
+   This file is part of libgpiod.
+
+   Copyright (C) 2022 Bartosz Golaszewski <[email protected]>
+
+   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

Quoted 2 lines · Kent Gibson

+# Copyright (C) 2022 Bartosz Golaszewski <[email protected]>

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.

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.

Quoted 9 lines · Bartosz Golaszewski

Quoted 2 lines · Kent Gibson

+# Copyright (C) 2022 Bartosz Golaszewski <[email protected]>

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.

Quoted 5 lines

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?