From cffb0e19ec711251e4de15aee37ad6e09832e6ec Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Wed, 1 Nov 2023 11:44:41 -0700 Subject: [PATCH] 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 Co-authored-by: pearce8 --- .github/dependabot.yml | 6 +++ .github/workflows/docs.yml | 62 +++++++++++++++++++++++++ .github/workflows/requirements/docs.txt | 3 ++ .gitignore | 3 ++ README.rst | 3 +- docs/1-getting-started.rst | 13 +++--- docs/2-benchpark-list.rst | 15 +++--- docs/4-benchpark-setup.rst | 7 ++- docs/5-build-experiment.rst | 15 +++--- docs/6-run-experiment.rst | 12 ++--- docs/Makefile | 20 ++++++++ docs/add-a-system-config.rst | 4 +- docs/add-an-experiment.rst | 4 +- docs/conf.py | 28 +++++++++++ docs/index.rst | 20 ++++++++ docs/make.bat | 35 ++++++++++++++ docs/spack.yaml | 12 +++++ 17 files changed, 227 insertions(+), 35 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/requirements/docs.txt create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/spack.yaml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..1ef1752e0 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +versions: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..25ddc417b --- /dev/null +++ b/.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 diff --git a/.github/workflows/requirements/docs.txt b/.github/workflows/requirements/docs.txt new file mode 100644 index 000000000..ee2e798f6 --- /dev/null +++ b/.github/workflows/requirements/docs.txt @@ -0,0 +1,3 @@ +# docs +sphinx==7.2.6 +sphinx-rtd-theme==1.3.0 diff --git a/.gitignore b/.gitignore index b867c7b2d..a104b6781 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ *~ \#*\# __pycache__ +_build +spack.lock +.spack-env diff --git a/README.rst b/README.rst index a262c9a87..c537bded9 100644 --- a/README.rst +++ b/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 diff --git a/docs/1-getting-started.rst b/docs/1-getting-started.rst index 2b47754a9..92e0228f5 100644 --- a/docs/1-getting-started.rst +++ b/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 git@github.com:LLNL/benchpark.git - cd benchpark + git clone git@github.com: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`. + diff --git a/docs/2-benchpark-list.rst b/docs/2-benchpark-list.rst index b4bdefb2e..85262a7e3 100644 --- a/docs/2-benchpark-list.rst +++ b/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`. diff --git a/docs/4-benchpark-setup.rst b/docs/4-benchpark-setup.rst index f7c088e08..a0ea16c13 100644 --- a/docs/4-benchpark-setup.rst +++ b/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/) (everything from source/experiments/) -``benchpark setup`` will output -`Build experiment <5-build-experiment.rst>`_ instructions. +``benchpark setup`` will output :doc:`5-build-experiment` instructions. diff --git a/docs/5-build-experiment.rst b/docs/5-build-experiment.rst index 52b17cce3..9c8378b56 100644 --- a/docs/5-build-experiment.rst +++ b/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 + cd ///workspace - . ///spack/share/spack/setup-env.sh - . ///ramble/share/ramble/setup-env.sh + . ///spack/share/spack/setup-env.sh + . ///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/) experiments/ / - / + / __ execute_experiment diff --git a/docs/6-run-experiment.rst b/docs/6-run-experiment.rst index 7ba577cfc..70f7e251e 100644 --- a/docs/6-run-experiment.rst +++ b/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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/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) diff --git a/docs/add-a-system-config.rst b/docs/add-a-system-config.rst index 07f1c7f0f..db7a4ca4e 100644 --- a/docs/add-a-system-config.rst +++ b/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, diff --git a/docs/add-an-experiment.rst b/docs/add-an-experiment.rst index 3ab67d031..0d063018a 100644 --- a/docs/add-an-experiment.rst +++ b/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, diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..768340c5d --- /dev/null +++ b/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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..0ba9607e3 --- /dev/null +++ b/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 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..32bb24529 --- /dev/null +++ b/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 diff --git a/docs/spack.yaml b/docs/spack.yaml new file mode 100644 index 000000000..ce520e3fc --- /dev/null +++ b/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