ReadTheDocs Configuration File (#512)

Adding readthedocs config file and robots.txt generation.

[ reviewed by @ashao @mellis13 ]
[ committed by @amandarichardsonn ]

.readthedocs.yaml

@@ -0,0 +1,41 @@
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  jobs:
+    post_checkout:
+      # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
+      # You can add any other files or directories that you'd like here as well,
+      # like your docs requirements file, or other files that will change your docs build.
+      #
+      # If there are no changes (git diff exits with 0) we force the command to return with 183.
+      # This is a special exit code on Read the Docs that will cancel the build immediately.
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- doc/ .readthedocs.yaml;
+        then
+          exit 183;
+        fi
+    pre_create_environment:
+      - git clone --depth 1 https://github.com/CrayLabs/SmartRedis.git smartredis
+      - git clone --depth 1 https://github.com/CrayLabs/SmartDashboard.git smartdashboard
+    post_create_environment:
+      - python -m pip install .
+      - cd smartredis; python -m pip install .
+      - cd smartredis/doc; doxygen Doxyfile_c; doxygen Doxyfile_cpp; doxygen Doxyfile_fortran
+      - ln -s smartredis/examples ./examples
+      - cd smartdashboard; python -m pip install .
+    pre_build:
+      - python -m sphinx -b linkcheck doc/ $READTHEDOCS_OUTPUT/linkcheck
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+  fail_on_warning: true
+
+python:
+   install:
+   - requirements: doc/requirements-doc.txt

doc/changelog.rst

@@ -18,15 +18,19 @@ To be released at some future point in time
 
 Description
 
+- ReadTheDocs config file added and enabled on PRs
 - Enforce changelog updates
 - Remove deprecated SmartSim modules
 - SmartSim Documentation refactor
 - Update the version of Redis from `7.0.4` to `7.2.4`
-- Update Experiment API typing
 - Fix publishing of development docs
+- Update Experiment API typing
 
 Detailed Notes
 
+- Add readthedocs configuration file and enable readthedocs builds
+  on pull requests. Additionally added robots.txt file generation
+  when readthedocs environment detected. (SmartSim-PR512_)
 - Add Github Actions workflow that checks if changelog is edited
   on pull requests into develop. (SmartSim-PR518_)
 - Removed deprecated SmartSim modules: slurm and mpirunSettings.
@@ -39,9 +43,10 @@ Detailed Notes
   was failing due to a lack of space within the container. This was fixed
   by including an additional Github action that removes some unneeded
   software and files that come from the default Github Ubuntu container.
-  (SmartSim-PR-PR504_)
+  (SmartSim-PR504_)
 - Update the generic `t.Any` typehints in Experiment API. (SmartSim-PR501_)
 
+.. _SmartSim-PR512: https://github.com/CrayLabs/SmartSim/pull/512
 .. _SmartSim-PR518: https://github.com/CrayLabs/SmartSim/pull/518
 .. _SmartSim-PR514: https://github.com/CrayLabs/SmartSim/pull/514
 .. _SmartSim-PR463: https://github.com/CrayLabs/SmartSim/pull/463

doc/conf.py

@@ -88,6 +88,13 @@
 # a list of builtin themes.
 html_theme = "sphinx_book_theme"
 
+# Check if the environment variable is set to 'True'
+if os.environ.get('READTHEDOCS') == "True":
+    # If it is, generate the robots.txt file
+    with open('./robots.txt', 'w') as f:
+        f.write("# Disallow crawling of the Read the Docs URL\nUser-agent: *\nDisallow: /en/")
+    html_extra_path = ['./robots.txt']
+
 # 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".