add configuration files for docs

modify requirements for latest sphinx version

testing if theme_override is the issue

customize css for version dropdown

try to get css changes to load

add sphinx built-in copy/paste button

add sphinx-copybutton to requirements

remove sphinx-copybutton

attempting custom css change

testing if we need theme_overrides.css anymore

remove unused file and revert custom.css back to normal

update Makefile to work with requirements.txt

added docs modifications to CHANGELOG

Fix footer styling in docs

attempt to fix styling issue on variables page

try to get themes_overrides to work

fix tab issues

styles pls work im begging

adding html_css_files var for the 5th time

testing whether this file is being loaded at all

will this make it load?

purposefully breaking conf.py as a test

trying complete relative path

try changing sidebar style instead of table

moving the z-index style to different div

commenting out custom.js as a test

first draft of overflow fix

swap styling order

test if second @media tag breaks css

fix potential issue with @media tags

still trying to get @media to work

trying to get styles to update on the actual site

pls just load

try a fix where I import alabastor's stylesheet

remove @import and add html_context to conf

remove html_context

modify variables table to use code blocks for col 3

remove theme_overrides again and modify CHANGELOG

Fix footer styling and horizontal scroll overalp for variables page

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.8"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ranks 0 and 1 of a multi-rank allocation
 - Added additional argument in test definitions to allow for a "cleanup" command
 - Capability for non-user block in yaml
+- .readthedocs.yaml and requirements.txt files for docs
 
 ### Changed
 - Rename lgtm.yml to .lgtm.yml
@@ -24,13 +25,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update requirements to require redis 4.3.4 for acl user channel support
 - Updated tutorial documentation to use merlin server over manual redis installation.
 - Added ssl to the broker and results backend server checks when "merlin info" is called
+- Removed theme_override.css from docs/_static/ since it is no longer needed with the updated version of sphinx
+- Updated docs/Makefile to include a pip install for requirements and a clean command
 
 ### Fixed
 - Fixed return values from scripts with main() to fix testing errors. 
 - CI test for CHANGELOG modifcations
 - Fix the cert_req typo in the merlin config docs, it should read cert_reqs
 - Removed emoji from issue templates that were breaking doc builds
 - Including .temp template files in MANIFEST
+- Styling in the footer for docs
+- Horizontal scroll overlap in the variables page of the docs
 
 ## [1.8.5]
 ### Added

docs/Makefile

@@ -23,6 +23,9 @@ view: code-docs html
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	pip install -r requirements.txt
 	echo $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+clean:
+	rm -rf build/

docs/requirements.txt

@@ -0,0 +1,56 @@
+#
+# This file is autogenerated by pip-compile with python 3.8
+# To update, run:
+#
+#    pip-compile requirements.in
+#
+alabaster==0.7.12
+    # via sphinx
+babel==2.10.3
+    # via sphinx
+certifi==2022.9.24
+    # via requests
+charset-normalizer==2.1.1
+    # via requests
+docutils==0.17.1
+    # via sphinx
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==5.0.0
+    # via sphinx
+jinja2==3.0.3
+    # via sphinx
+markupsafe==2.1.1
+    # via jinja2
+packaging==21.3
+    # via sphinx
+pygments==2.13.0
+    # via sphinx
+pyparsing==3.0.9
+    # via packaging
+pytz==2022.5
+    # via babel
+requests==2.28.1
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.3.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+urllib3==1.26.12
+    # via requests
+zipp==3.10.0
+    # via importlib-metadata

docs/source/_static/custom.css

@@ -22,3 +22,15 @@ div.sphinxsidebar {
     max-height: 100%;
     overflow-y: auto;
 }
+td {
+	max-width: 300px;
+}
+@media screen and (min-width: 875px) {
+	.sphinxsidebar {
+		background-color: #fff;
+		margin-left: 0;
+		z-index: 1;
+		height: 100vh;
+		top: 0px;
+	}
+}

docs/source/conf.py

@@ -101,12 +101,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-html_context = {
-    'css_files': [
-        '_static/theme_overrides.css',  # override wide tables in RTD theme
-    ],
-}
+html_css_files = ['custom.css']
 
+#html_context = {"css_files": ["_static/custom.css"]}
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -188,8 +185,8 @@ def setup(app):
     try:
         app.add_javascript("custom.js")
         app.add_javascript("https://cdn.jsdelivr.net/npm/clipboard@1/dist/clipboard.min.js")
-        app.add_stylesheet('custom.css')
+        #app.add_stylesheet('custom.css')
     except AttributeError:
-        app.add_css_file('custom.css')
+        #app.add_css_file('custom.css')
         app.add_js_file("custom.js")
         app.add_js_file("https://cdn.jsdelivr.net/npm/clipboard@1/dist/clipboard.min.js")

docs/source/merlin_variables.rst

@@ -31,73 +31,138 @@ The directory structure of merlin output looks like this:
 Reserved variables
 ------------------
 .. list-table:: Study variables that Merlin uses. May be referenced within a specification file, but not reassigned or overridden.
-
-  * - Variable
-    - Description
-    - Example Expansion
-  * - ``$(SPECROOT)``
-    -  Directory path of the specification file.
-    - ``/globalfs/user/merlin_workflows``
-  * - ``$(OUTPUT_PATH)``
-    - Directory path the study output will be written to. If not defined
-      will default to the current working directory. May be reassigned or
-      overridden.
-    - ``./studies``
-  * - ``$(MERLIN_TIMESTAMP)``
-    - The time a study began. May be used as a unique identifier.
-    - ``"YYYYMMDD-HHMMSS"``
-  * - ``$(MERLIN_WORKSPACE)``
-    - Output directory generated by a study at ``OUTPUT_PATH``. Ends with
-      ``MERLIN_TIMESTAMP``.
-    - ``$(OUTPUT_PATH)/ensemble_name_$(MERLIN_TIMESTAMP)``
-  * - ``$(WORKSPACE)``
-    - The workspace directory for a single step.
-    - ``$(OUTPUT_PATH)/ensemble_name_$(MERLIN_TIMESTAMP)/step_name/``
-  * - ``$(MERLIN_INFO)``
-    - Directory within ``MERLIN_WORKSPACE`` that holds the provenance specs and sample generation results.
-      Commonly used to hold ``samples.npy``.
-    - ``$(MERLIN_WORKSPACE)/merlin_info/``
-  * - ``$(MERLIN_SAMPLE_ID)``
-    - Sample index in an ensemble
-    - ``0`` ``1`` ``2`` ``3``
-  * - ``$(MERLIN_SAMPLE_PATH)``
-    - Path in the sample directory tree to a sample's directory, i.e. where the
-      task is actually run.
-    - ``/0/0/0/`` ``/0/0/1/`` ``/0/0/2/`` ``/0/0/3/``
-  * - ``$(MERLIN_GLOB_PATH)``
-    - All of the directories in a simulation tree as a glob (*) string
-    - ``/\*/\*/\*/\*``
-  * - ``$(MERLIN_PATHS_ALL)``
-    - A space delimited string of all of the paths;
-      can be used as is in bash for loop for instance with:
-
-      .. code-block:: bash
-
-         for path in $(MERLIN_PATHS_ALL)
-           do
-             ls $path
-           done
-
-         for path in $(MERLIN_PATHS_ALL)
-         do
-           ls $path
-         done
-    - ``0/0/0 0/0/1 0/0/2 0/0/3``
-  * - ``$(MERLIN_SAMPLE_VECTOR)``
-    - Vector of merlin sample values
-    - ``$(SAMPLE_COLUMN_1) $(SAMPLE_COLUMN_2) ...``
-  * - ``$(MERLIN_SAMPLE_NAMES)``
-    - Names of merlin sample values
-    - ``SAMPLE_COLUMN_1 SAMPLE_COLUMN_2 ...``
-  * - ``$(MERLIN_SPEC_ORIGINAL_TEMPLATE)``
-    - Copy of original yaml file passed to ``merlin run``.
-    - ``$(MERLIN_INFO)/*.orig.yaml``
-  * - ``$(MERLIN_SPEC_EXECUTED_RUN)``
-    - Parsed and processed yaml file with command-line variable substitutions included.
-    - ``$(MERLIN_INFO)/*.partial.yaml``
-  * - ``$(MERLIN_SPEC_ARCHIVED_COPY)``
-    - Archive version of ``MERLIN_SPEC_EXECUTED_RUN`` with all variables and paths fully resolved.
-    - ``$(MERLIN_INFO)/*.expanded.yaml``
+   :widths: 25 50 25
+   :header-rows: 1
+
+   * - Variable
+     - Description
+     - Example Expansion
+
+   * - ``$(SPECROOT)``
+     -  Directory path of the specification file.
+     -
+        ::
+ 
+            /globalfs/user/merlin_workflows
+ 
+   * - ``$(OUTPUT_PATH)``
+     - Directory path the study output will be written to. If not defined
+       will default to the current working directory. May be reassigned or
+       overridden.
+     - 
+        ::
+
+            ./studies
+ 
+   * - ``$(MERLIN_TIMESTAMP)``
+     - The time a study began. May be used as a unique identifier.
+     - 
+        ::
+
+            "YYYYMMDD-HHMMSS"
+ 
+   * - ``$(MERLIN_WORKSPACE)``
+     - Output directory generated by a study at ``OUTPUT_PATH``. Ends with
+       ``MERLIN_TIMESTAMP``.
+     - 
+        ::
+ 
+            $(OUTPUT_PATH)/ensemble_name_$(MERLIN_TIMESTAMP)
+ 
+   * - ``$(WORKSPACE)``
+     - The workspace directory for a single step.
+     - 
+        ::
+
+            $(OUTPUT_PATH)/ensemble_name_$(MERLIN_TIMESTAMP)/step_name/``
+ 
+   * - ``$(MERLIN_INFO)``
+     - Directory within ``MERLIN_WORKSPACE`` that holds the provenance specs and sample generation results.
+       Commonly used to hold ``samples.npy``.
+     - 
+        ::
+
+            $(MERLIN_WORKSPACE)/merlin_info/
+ 
+   * - ``$(MERLIN_SAMPLE_ID)``
+     - Sample index in an ensemble
+     - 
+        ::
+
+            0 1 2 3
+ 
+   * - ``$(MERLIN_SAMPLE_PATH)``
+     - Path in the sample directory tree to a sample's directory, i.e. where the
+       task is actually run.
+     - 
+        ::
+        
+            /0/0/0/ /0/0/1/ /0/0/2/ /0/0/3/
+ 
+   * - ``$(MERLIN_GLOB_PATH)``
+     - All of the directories in a simulation tree as a glob (*) string
+     - 
+        ::
+
+            /*/*/*/*
+ 
+   * - ``$(MERLIN_PATHS_ALL)``
+     - A space delimited string of all of the paths;
+       can be used as is in bash for loop for instance with:
+
+       .. code-block:: bash
+ 
+          for path in $(MERLIN_PATHS_ALL)
+            do
+              ls $path
+            done
+ 
+          for path in $(MERLIN_PATHS_ALL)
+          do
+            ls $path
+          done
+     - 
+        ::
+
+            0/0/0 
+            0/0/1 
+            0/0/2 
+            0/0/3
+ 
+   * - ``$(MERLIN_SAMPLE_VECTOR)``
+     - Vector of merlin sample values
+     - 
+        ::
+
+            $(SAMPLE_COLUMN_1) $(SAMPLE_COLUMN_2) ...
+ 
+   * - ``$(MERLIN_SAMPLE_NAMES)``
+     - Names of merlin sample values
+     - 
+        ::
+
+            SAMPLE_COLUMN_1 SAMPLE_COLUMN_2 ...
+ 
+   * - ``$(MERLIN_SPEC_ORIGINAL_TEMPLATE)``
+     - Copy of original yaml file passed to ``merlin run``.
+     - 
+        ::
+
+            $(MERLIN_INFO)/*.orig.yaml
+ 
+   * - ``$(MERLIN_SPEC_EXECUTED_RUN)``
+     - Parsed and processed yaml file with command-line variable substitutions included.
+     - 
+        ::
+
+            $(MERLIN_INFO)/*.partial.yaml
+ 
+   * - ``$(MERLIN_SPEC_ARCHIVED_COPY)``
+     - Archive version of ``MERLIN_SPEC_EXECUTED_RUN`` with all variables and paths fully resolved.
+     - 
+        ::
+
+            $(MERLIN_INFO)/*.expanded.yaml
 
 
 User variables