From c120fd9650204be58a7e27a50b1f8b880f91b889 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Obih=C3=B6rnchen?= Date: Tue, 13 Feb 2024 01:53:36 +0100 Subject: [PATCH] Fix and improve readthedocs docu --- .readthedocs.yaml | 29 +++++++++++++++++++++++++++++ docs/README.md | 13 ++----------- docs/requirements.txt | 5 ++++- docs/source/conf.py | 12 ++++-------- 4 files changed, 39 insertions(+), 20 deletions(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..d9babb1531 --- /dev/null +++ b/.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 diff --git a/docs/README.md b/docs/README.md index 3c105885e4..31d0383308 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 51dfb14bc0..51aec89ff6 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index a50ed66768..4abc4abda6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -31,6 +31,7 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx_search.extension', ] # Add any paths that contain templates here, relative to this directory. @@ -66,7 +67,7 @@ # # 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 @@ # 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