Fix the documentation setup for readthedocs (#88)

Author: marcosbento

.readthedocs.yml

@@ -0,0 +1,17 @@
+
+version: 2 
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "doc/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Define the requirements required to build the documentation
+python:
+   install:
+     - requirements: doc/requirements.txt

cmake/FindFFTW.cmake

@@ -22,17 +22,20 @@
 # Search procedure
 # ----------------
 #
-# 1) FFTW_LIBRARIES and FFTW_INCLUDE_DIRS set by user
-#    --> Nothing is searched and these variables are used instead
+# * FFTW_LIBRARIES and FFTW_INCLUDE_DIRS set by user
+#   
+#   * Nothing is searched and these variables are used instead
 #
-# 2) Find MKL implementation via FFTW_ENABLE_MKL
-#    --> If FFTW_ENABLE_MKL is explicitely set to ON, only MKL is considered
-#        If FFTW_ENABLE_MKL is explictely set to OFF, MKL will not be considered
-#        If FFTW_ENABLE_MKL is undefined, MKL is preferred unless ENABLE_MKL is explicitely set to OFF
-#    --> MKLROOT environment variable helps to detect MKL (See FindMKL.cmake)
+# * Find MKL implementation via FFTW_ENABLE_MKL
 #
-# 3) Find official FFTW impelementation
-#    --> FFTW_ROOT variable / environment variable helps to detect FFTW
+#   * If FFTW_ENABLE_MKL is explicitely set to ON, only MKL is considered
+#   * If FFTW_ENABLE_MKL is explictely set to OFF, MKL will not be considered
+#   * If FFTW_ENABLE_MKL is undefined, MKL is preferred unless ENABLE_MKL is explicitely set to OFF
+#   * Note: MKLROOT environment variable helps to detect MKL (See FindMKL.cmake)
+#
+# * Find official FFTW impelementation
+#
+#   * FFTW_ROOT variable / environment variable helps to detect FFTW
 #
 # Components
 # ----------

cmake/ecbuild_add_lang_flags.cmake

@@ -10,7 +10,7 @@
 #.rst:
 #
 # ecbuild_add_lang_flags
-# =====================
+# ======================
 #
 # This is mostly an internal function of ecbuild, wrapped by the macros ecbuild_add_c_flags,
 # ecbuild_add_cxx_flags and ecbuild_add_fortran_flags.

cmake/ecbuild_compiler_flags.cmake

@@ -76,7 +76,7 @@ endmacro()
 #.rst:
 #
 # ecbuild_purge_compiler_flags
-# ======================
+# ============================
 #
 # Purge compiler flags for a given language ::
 #
@@ -156,7 +156,7 @@ endmacro()
 #.rst:
 #
 # ecbuild_override_compiler_flags
-# ======================
+# ===============================
 #
 # Purge existing CMAKE_<lang>_FLAGS flags and trigger the use of per source
 # file overrideable flags (see ``Using custom compilation flags`` for an

cmake/ecbuild_find_package.cmake

@@ -111,7 +111,8 @@
 #        - ``ENV{<name>_DIR}``
 #        - ``ENV{CMAKE_PREFIX_PATH}``
 #        - ``system paths``
-#       See CMake documentation of ``find_package()`` for details on search
+#
+#       See CMake documentation of ``find_package()`` for details.
 #
 # 4.  Fail if the package was not found and is REQUIRED.
 #

cmake/ecbuild_find_package_search_hints.cmake

@@ -41,6 +41,7 @@
 #      If CMake version < 3.12:
 #        If <name>_DIR not defined in scope or environment, but <name>_ROOT IS defined in scope or environment
 #           Try setting <name>_DIR to a valid cmake-dir deduced from <name>_ROOT.
+#
 #           Warning: Deduction is not feature-complete (it could be improved, but should now cover 99% of cases)
 #                    It is advised to use CMake 3.12 instead.
 #

doc/cmake.py

@@ -21,10 +21,11 @@
 CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
                                   bygroups(Operator, Name.Variable, Operator)))
 
+
 # Monkey patch for sphinx generating invalid content for qcollectiongenerator
 # https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords
-from sphinx.util.pycompat import htmlescape
-from sphinx.builders.qthelp import QtHelpBuilder
+import html
+from sphinxcontrib.qthelp import QtHelpBuilder
 old_build_keywords = QtHelpBuilder.build_keywords
 
 
@@ -35,7 +36,7 @@ def new_build_keywords(self, title, refs, subitems):
         before, rest = item.split("ref=\"", 1)
         ref, after = rest.split("\"")
         if ("<" in ref and ">" in ref):
-            new_items.append(before + 'ref="' + htmlescape(ref) + '"' + after)
+            new_items.append(before + 'ref="' + html.escape(ref) + '"' + after)
         else:
             new_items.append(item)
     return new_items

doc/conf.py

@@ -42,14 +42,11 @@ def parse_version(ver_str):
 
 html_show_sourcelink = True
 html_static_path = [os.path.join(here, 'static')]
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 html_title = 'ecBuild %s Documentation' % release
 html_short_title = '%s Documentation' % release
 html_favicon = os.path.join(here, 'static', 'ecbuild.ico')
-# Not supported yet by sphinx:
-# https://bitbucket.org/birkenfeld/sphinx/issue/1448/make-qthelp-more-configurable
-# qthelp_namespace = "org.cmake"
-# qthelp_qch_name = "CMake-300.qch"
+
 
 # Extract the docs from the .cmake files
 from generate import generate

doc/requirements.txt

@@ -0,0 +1,5 @@
+# These are the requirements for readthedoc
+docutils
+Sphinx>=4.4.0
+setuptools>=51.0.0
+sphinx-rtd-theme>=0.5.0