Add initial sphinx configuration and supporting GitHub Actions CI (#37)

* Add initial sphinx docs and github actions ci

* Fix file ending for github actions

* Fix typo in github workflow

* Reformat deploy job to fix permissions issues

* docs updates

* add flag to ramble

---------

Co-authored-by: Stephanie Brink <[email protected]>
Co-authored-by: pearce8 <[email protected]>

.github/dependabot.yml

@@ -0,0 +1,6 @@
+versions: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Build & Deploy docs site to GitHub Pages
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+    branches:
+      - develop
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+    - name: Setup Python
+      uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
+      with:
+        python-version: '3.11'
+        cache: 'pip'
+        cache-dependency-path: '.github/workflows/requirements/docs.txt'
+
+    - name: Setup GitHub Pages
+      id: pages
+      uses: actions/configure-pages@f156874f8191504dae5b037505266ed5dda6c382
+
+    - name: Install Sphinx and Theme via Pip
+      run: |
+        pip install -r .github/workflows/requirements/docs.txt
+
+    - name: Build with sphinx
+      run: |
+        sphinx-build docs/ _build
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@a753861a5debcf57bf8b404356158c8e1e33150c
+      if: github.ref == 'refs/heads/develop'
+      with:
+        path: ./_build
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/develop'
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@9dbe3824824f8a1377b8e298bafde1a50ede43e5

.github/workflows/requirements/docs.txt

@@ -0,0 +1,3 @@
+# docs
+sphinx==7.2.6
+sphinx-rtd-theme==1.3.0

.gitignore

@@ -2,3 +2,6 @@
 *~
 \#*\#
 __pycache__
+_build
+spack.lock
+.spack-env

README.rst

@@ -71,6 +71,7 @@ ACM, New York, NY, USA, 9 pages.
 
 License
 -------
-Benchpark is released under the Apache 2.0 w/ LLVM Exception license. For more details see the [LICENSE](/LICENSE) file.
+Benchpark is released under the Apache 2.0 w/ LLVM Exception license. For more
+details see the [LICENSE](./LICENSE) file.
 
 LLNL-CODE-850629

docs/1-getting-started.rst

@@ -1,11 +1,12 @@
-=========
-Getting started with Benchpark
-=========
+==============================
+Getting Started with Benchpark
+==============================
 
 Git is needed to clone Benchpark, and Python 3.8+ is needed to run Benchpark::
 
-  git clone [email protected]:LLNL/benchpark.git   
-  cd benchpark
+    git clone [email protected]:LLNL/benchpark.git
+    cd benchpark
 
 Now you are ready to look at the benchmarks and systems available in Benchpark,
-as described in `Benchpark list <2-benchpark-list.rst>`_
+as described in :doc:`2-benchpark-list`.
+

docs/2-benchpark-list.rst

@@ -1,10 +1,11 @@
-===================
-Benchpark list
-===================
+==============
+Benchpark List
+==============
+
 To list all benchmarks and systems available in Benchpark::
 
-  $ cd bin
-  $ benchpark list
+    cd bin
+    benchpark list
 
-Once you have decided on a ``system`` you will use, and the ``benchmark/ProgrammingModel`` to run, 
-you can proceed to `Benchpark setup <4-benchpark-setup.rst>`_.
+Once you have decided on a ``system`` you will use, and the ``benchmark/ProgrammingModel``
+to run, you can proceed to :doc:`4-benchpark-setup`.

docs/4-benchpark-setup.rst

@@ -1,11 +1,11 @@
 ===============
-Benchpark setup 
+Benchpark Setup
 ===============
 
 Select a benchmark experiment to run, along with the programming model to use, and a system to run them on.
 Also choose the workspace for your experiment::
 
-  $ benchpark setup benchmark/ProgrammingModel system /output/path/to/workspace_root
+    benchpark setup benchmark/ProgrammingModel system /output/path/to/workspace_root
 
 where:
 
@@ -27,5 +27,4 @@ with the following directory structure::
                             (everything from source/configs/<system>)
                             (everything from source/experiments/<benchmark>)
 
-``benchpark setup`` will output 
-`Build experiment <5-build-experiment.rst>`_ instructions.
+``benchpark setup`` will output :doc:`5-build-experiment` instructions.

docs/5-build-experiment.rst

@@ -2,16 +2,17 @@
 Build experiment
 ================
 
-`Benchmark setup <4-benchmark-setup.rst>`_ will output instructions to follow::
+``benchpark setup`` will output instructions to follow::
 
-  cd <workspace_root>/<benchmark/ProgrammingModel>/<system>/workspace
+   cd <workspace_root>/<benchmark/ProgrammingModel>/<system>/workspace
 
-  . <workspace_root>/<benchmark/ProgrammingModel>/<system>/spack/share/spack/setup-env.sh
-  . <workspace_root>/<benchmark/ProgrammingModel>/<system>/ramble/share/ramble/setup-env.sh
+   . <workspace_root>/<benchmark/ProgrammingModel>/<system>/spack/share/spack/setup-env.sh
+   . <workspace_root>/<benchmark/ProgrammingModel>/<system>/ramble/share/ramble/setup-env.sh
 
-  export SPACK_DISABLE_LOCAL_CONFIG=1
+   export SPACK_DISABLE_LOCAL_CONFIG=1
+
+   ramble -P -D . workspace setup  
 
-  ramble -P -D . workspace setup  
 
 which will build the source code and set up the following workspace directory structure::
 
@@ -27,6 +28,6 @@ which will build the source code and set up the following workspace directory st
                             (everything from source/experiments/<benchmark>)
                         experiments/
                             <benchmark>/
-                                <problem>/   
+                                <problem>/
                                     <benchmark>_<ProgrammingModel>_<problem>
                                         execute_experiment

docs/6-run-experiment.rst

@@ -1,10 +1,10 @@
-=================================
+==================================
 Running an Experiment in Benchpark
-=================================
+==================================
 
 To run all of the experiments in the workspace::
 
-  ramble -D . on
+   ramble -P -D . on
 
 An output file is generated for each experiment in its unique directory::
 
@@ -31,11 +31,11 @@ An output file is generated for each experiment in its unique directory::
 
 An experiment instance can also be executed individually by directly invoking its ``execute_experiment`` script 
 (e.g., ``$workspace/experiments/amg2023/problem1/amg2023_cuda11.8.0_problem1_1_8_2_2_2_10_10_10/execute_experiment``).
-Note that rerunning the experiment may overwrite any existing output files in the directory.
+Note that re-running the experiment may overwrite any existing output files in the directory.
 
 Analyze the experiment results 
------------------------------------------
-Once the experiments have been run, the command:: 
+------------------------------
+Once the experiments have been run, the command::
 
   ramble -P -D . workspace analyze 
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/add-a-system-config.rst

@@ -1,6 +1,6 @@
-======================
+=============================
 Adding a System Configuration
-======================
+=============================
 
 ``benchpark/configs`` contains a directory for each system specified in Benchpark.
 If the software stack on your system is unlike the available configurations, 

docs/add-an-experiment.rst

@@ -1,6 +1,6 @@
-==================
+=================
 Add an Experiment
-==================
+=================
 
 Experiment specifications are located in ``$benchpark/experiments``. 
 They are organized by the *ProgrammingModel* used for on-node parallelization for the experiment, 

docs/conf.py

@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Benchpark'
+copyright = '2023, LLNS LLC'
+author = 'Olga Pearce, Alec Scott, Peter Scheibel, Greg Becker, Riyaz Haque, and Nathan Hanford'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx_rtd_theme',
+]
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.spack-env']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,20 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+   :caption: Getting Started
+
+   1-getting-started
+   2-benchpark-list
+   4-benchpark-setup
+   5-build-experiment
+   6-run-experiment
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contributing
+
+   add-a-system-config
+   add-an-experiment
+   add-a-benchmark

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/spack.yaml

@@ -0,0 +1,12 @@
+# This is a Spack Environment file.
+#
+# It describes a set of packages to be installed, along with
+# configuration settings.
+spack:
+  # add package specs to the `specs` list
+  specs:
+  - py-sphinx
+  - py-sphinx-rtd-theme
+  view: true
+  concretizer:
+    unify: true