Merge pull request #7423 from Obihoernchen/readthedocs

Fix and improve readthedocs docu

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+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 "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/README.md

@@ -6,18 +6,9 @@ The xCAT docs are hosted here: https://xcat-docs.readthedocs.io/ and are written
 
 * Clone this project 
 
-* Install or update sphinx (See: https://pip.readthedocs.io/)
+* Install dependencies (See: https://pip.readthedocs.io/)
    ```
-   pip install sphinx
-   ```
-   or
-   ```
-   pip install sphinx --upgrade
-   ```
-
-* Install ReadTheDocs theme
-   ```
-   pip install sphinx_rtd_theme
+   pip install --user -r requirements.txt
    ```
 
 * Build the Docs

docs/requirements.txt

@@ -1 +1,4 @@
-docutils==0.17
+sphinx==7.2.6
+sphinx_rtd_theme==2.0.0
+docutils==0.20.1
+readthedocs-sphinx-search==0.3.2

docs/source/conf.py

@@ -31,6 +31,7 @@ import shlex
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx_search.extension',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -66,7 +67,7 @@ release = '2.16.6'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -144,13 +145,8 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-import os
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if on_rtd:
-    html_theme = 'default'
-else:
-    # some of the popular themes: alabaster, sphinx_rtd_theme, classic, nature
-    html_theme = 'sphinx_rtd_theme'
+# some of the popular themes: alabaster, sphinx_rtd_theme, classic, nature
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the