doc: add configuration to generate doxygen documentation on readthedocs.
PATCH 1/1 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 doxygen C/C++ documentation on readthedocs.
---
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
.readthedocs.yaml new file +29 -0
@@ -0,0 +1,29 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later + +# +# This file is part of libgpiod. +# +# Copyright (C) 2022 Bartosz Golaszewski <[email protected]> +# +# 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
70 lines not on this page · raw message
sphinx/index.rst new file +24 -0
@@ -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`
Signature · 1 line
2.35.1
Quoted 147 lines · 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 <[email protected]>---
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.readthedocs.yaml new file +29
-0@@ -0,0 +1,29 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later + +# +# This file is part of libgpiod. +# +# Copyright (C) 2022 Bartosz Golaszewski <[email protected]> +# +# 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@@ -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 +0
-0
sphinx/index.rst line 6
Quoted 6 lines
sphinx/index.rst new file +6
-0@@ -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]>
All looks good to me except that Copyright should be yours here, not mine. :)
Bart
Quoted 21 lines
sphinx/index.rst new file +18
-1+ + 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
Quoted 8 lines · Bartosz Golaszewski
Quoted 7 lines · 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 <[email protected]>
[snip]
Quoted 12 lines
sphinx/index.rst line 6
Quoted 9 lines
sphinx/index.rst new file +6
-0@@ -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]>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.