Merge pull request #216 from lanl/blb/organizational

Add sphinx read the docs, organizational docs

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,3 +16,4 @@ detail.  Why is this change required?  What problem does it solve?-->
 - [ ] Adds a test for any bugs fixed. Adds tests for new features.
 - [ ] Format your changes by calling `scripts/bash/format.sh`.
 - [ ] Explain what you did.
+- [ ] Make any necessary changes to the documentation.

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Build and Deploy docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types:
+      - created
+
+jobs:
+    docs:
+      name: build and deploy docs
+      runs-on: ubuntu-latest
+
+      steps:      
+        - name: Checkout code
+          uses: actions/checkout@v2
+          with:
+            fetch-depth: 0
+        - name: Set system to non-interactive mode
+          run: export DEBIAN_FRONTEND=noninteractive
+        - name: install dependencies
+          run: |
+            pip install sphinx
+            pip install sphinx-sitemap
+            pip install sphinx-rtd-theme
+            pip install sphinx-multiversion
+            pip install sphinx-copybutton
+        - name: build docs
+          run: |
+            echo "Repo = ${GITHUB_REPOSITORY}"
+            cd doc/sphinx
+            # throw warnings as error to make sure docs properly build
+            make multiversion SPHINXOPTS="-W --keep-going -n"
+        - name: Deploy
+          if: ${{ (github.event.pull_request.head.repo.full_name == github.repository) || (github.ref == 'refs/heads/main') }}
+          uses: peaceiris/actions-gh-pages@v3.7.3
+          with:
+            github_token: ${{ secrets.GITHUB_TOKEN }}
+            publish_dir: ./doc/sphinx/_build/html
+            force_orphan: true

.gitignore

@@ -13,3 +13,4 @@ __pycache__
 *.swp
 *.png
 *~
+.ccls-cache/

CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# Phoebus Community Code of Conduct
+
+We as users, members, contributors, and leaders agree to make participation in our
+community a harassment-free experience for everyone.
+We will interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+We agree to uphold the [LANL Code of Conduct](https://cdn.lanl.gov/files/code-of-conduct-1_312ce.pdf) in all spaces relevant. 
+Of note:
+
+
+>   -  Foster a mutually respectful working environment that is free from
+>      discrimination, intimidation, and harassment (including sexual
+>      harassment).
+>   -  Do not discriminate against others on the basis of any
+>      characteristic protected by law or LANL policy.
+>   -  Do not engage in behaviors that create an offensive, hostile, or
+>      intimidating work environment, including shouting, abusive
+>      language, threats of violence, the use of obscenities or other
+>      non-verbal expressions of aggression, horseplay such as kicking
+>      co-workers’ chairs or using personal insults, or the use of
+>      offensive nicknames or other derogatory remarks.
+>   -  Avoid behavior that a reasonable person would find to be demeaning
+>      or humiliating.

CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing
+---
+
+To contribute to `Phoebus`, feel free to submit a pull request or open
+an issue.
+
+1.  Create a new fork of `main` where your changes can be made.
+2.  After completing, create a pull request, describe the final approach
+    and ensure the branch has no conflicts with current Regression Tests
+    and Formatting Checks.
+3.  Assign external reviewers (a minimum of 1, one of which should be a
+    Maintainer, and which cannot be the contributor). Provide concise
+    description of changes.
+4.  Once comments/feedback is addressed, the PR will be merged into the
+    main branch and changes will be added to list of changes in the next
+    release.
+5.  At present, Releases (with a git version tag) for the `main` branch
+    of `Phoebus` will occur at a 6 to 12 month cadence or following
+    implementation of a major enhancement or capability to the code
+    base.
+
+*Maintainers* of `Phoebus` will follow the same process for
+contributions as above except for the following differences: they may
+create branches directly within `Phoebus`, they will hold repository
+admin privileges, and actively participate in the technical review of
+contributions to `Phoebus`.
+
+# Pull request protocol
+
+When submitting a pull request, there is a default template that is
+automatically populated. The pull request should sufficiently summarize
+all changes. As necessary, tests should be added for new features of
+bugs fixed.
+
+Before a pull request will be merged, the code should be formatted. We
+use clang-format for this, pinned to version 12. The script
+`scripts/bash/format.sh` will apply `clang-format` to C++ source files
+in the repository as well as `black` to python files, if available. The
+script takes two CLI arguments that may be useful, `CFM`, which can be
+set to the path for your clang-format binary, and `VERBOSE`, which if
+set to `1` adds useful output. For example:
+
+``` bash
+CFM=clang-format-12 VERBOSE=1 ./scripts/bash/format.sh
+```
+
+In order for a pull request to merge, we require:
+
+-   Provide a thorough summary of changes, especially if they are
+    breaking changes
+-   Obey style guidleines (format with `clang-format` and pass the
+    necessary test)
+-   Pass the existing test suite
+-   Have at least one approval from a Maintainer
+-   If Applicable:
+    -   Write new tests for new features or bugs
+    -   Include or update documentation in `doc/`
+
+---
+
+# Test Suite
+
+Several sets of tests are triggered on a pull request: a static format
+check, a docs buld, and a suite of unit and regression tests. These are
+run through github\'s CPU infrastructure. These tests help ensure that
+modifications to the code do not break existing capabilities and ensure
+a consistent code style.
+
+## Adding Tests
+
+There are two primary categories of tests written in `Phoebus`: unit
+tests and regression tests.
+
+### Unit
+
+Unit tests live in `tst/unit/`. They are implemented using the
+[Catch2](https://github.com/catchorg/Catch2) unit testing framework.
+They are integrated with `cmake` and can be run, when enabled, with
+`ctest`. There are a few necessary `cmake` configurations to beuild
+tests:
+
++------------------------------+---------+------------------------------------------+
+| Option                       | Default | Description                              |
++==============================+=========+==========================================+
+| PHOEBUS\_ENABLE\_UNIT\_TESTS | OFF     | Enables Catch2 unit tests                |
++------------------------------+---------+------------------------------------------+
+| PHOEBUS\_ENABLE\_DOWNLOADS   | OFF     | Enables unit tests using tabulated EOS   |
++------------------------------+---------+------------------------------------------+
+
+### Regression
+
+Regression tests run existing simulations and test against saved output
+in order to verify sustained capabilities. They are implemented in
+Python in `test/regression/`. To run the tests you will need a Python
+environment with at least `numpy` and `h5py`. Tests can be ran manually
+as, e.g.,
+
+``` bash
+python linear_modes.py
+```
+
+This will build Phoebus locally in `phoebus/tst/regression/build` and
+run it in `phoebus/tst/regression/run`. Ensure that these directories do
+not already exist. Each script `test.py` has a correspodning \"gold
+file\" `test.gold`. The gold files contain the gold standard data that
+the output of the regression test is compared against. To generate new
+gold data, for example if a change is implemented that changes the
+behavior of a test (not erroneously) or a new test is created, run the
+test script with the `--upgold` option. This will create or update the
+corresponding `.gold` file. To add a new test:
+
+1.  Create a new test script.
+    -   Update the `modified_inputs` struct to change any input deck
+        options
+    -   Set the `variables` list to contain the quantities to test
+        against
+2.  Run the script with the `--upgold` option
+3.  Commit the test script and gold file
+4.  Update the CI to include the new test
+    (`phoebus/.github/workflows/tests.yml`)
+
+---
+See the [docs](https://lanl.github.io/phoebus) for further information
+about contributing to `Phoebus`.
+---
+
+## List of Current Maintainers of Phoebus
+---
+| Name     | Handle       | Team       |
+|----------|--------------|------------|
+| Brandon Barker | [@AstroBarker](https://www.github.com/AstroBarker) | Los Alamos National Lab |
+| Josh Dolence | [@jdolence](https://www.github.com/jdolence) | Los Alamos National Lab |
+| Carl Fields | [@carlnotsagan](https://www.github.com/carlnotsagan) | University of Arizona |
+| Mariam Gogilashvili | [@mari2895](https://www.github.com/mari2895) | Niels Bohr Institute |
+| Jonah Miller | [@Yurlungur](https://www.github.com/Yurlungur) | Los Alamos National Lab |
+| Jeremiah Murphy | [@curiousmiah](https://www.github.com/curiousmiah) | Florida State University |
+| Ben Ryan | [@brryan](https://www.github.com/brryan) | Los Alamos National Lab |

README.md

@@ -1,5 +1,8 @@
 phoebus
 ===
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/lanl/phoebus/tests.yml?branch=main)
+[![Documentation](https://github.com/lanl/phoebus/actions/workflows/docs.yml/badge.svg?branch=main)](https://lanl.github.io/phoebus/main/index.html)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
 Phifty One Ergs Blows Up a Star
 
@@ -73,7 +76,7 @@ Below are some example build commands
 
 ### MPI-parallel only
 
-The following will build `phoebus` with the `triple` problem with MPI parallelism but no shared memory parallelism
+The following will build `phoebus` with MPI parallelism but no shared memory parallelism
 ```bash
 cmake ..
 make -j
@@ -156,7 +159,7 @@ make -j
 
 Run phoebus from the `build` directory as
 ```bash
-./src/phoebus -i path/to/input/file.phin
+./src/phoebus -i path/to/input/file.pin
 ```
 The input files are in `phoebus/inputs/*`. There's typically one input file per problem setup file.
 
@@ -194,9 +197,15 @@ environment variable. For example:
 CFM=clang-format-12 ./scripts/bash/format.sh
 ```
 
+# Contribute
+We are always happy to have users contribute to `phoebus`.
+To contribute, create a fork and issue a pull request against the main branch. 
+For more details on how to contribute to `phoebus`, please see [CONTRIBUTING.md](CONTRIBUTING.md).
+We adhere to a [code of conduct](CODE_OF_CONDUCT.md).
+
 # Copyright
 
-© 2021. Triad National Security, LLC. All rights reserved.  This
+© 2021-2024. Triad National Security, LLC. All rights reserved.  This
 program was produced under U.S. Government contract 89233218CNA000001
 for Los Alamos National Laboratory (LANL), which is operated by Triad
 National Security, LLC for the U.S.  Department of Energy/National

doc/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<!-- This is needed to redirect to the main version when building docs -->
+<html>
+  <head>
+    <title>Redirecting to main branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="https://lanl.github.io/phoebus/main/index.html">
+  </head>
+</html>

doc/sphinx/.gitignore

@@ -0,0 +1,2 @@
+_build/
+!src/building.rst

doc/sphinx/Makefile

@@ -0,0 +1,27 @@
+# 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: sphinxhelp
+	$(info "Use make multiversion to use sphinx-multiversion")
+
+sphinxhelp:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+multiversion: Makefile
+	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html"
+	cp ../index.html "$(BUILDDIR)/html"
+
+.PHONY: help sphinxhelp multiversion 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)

doc/sphinx/_static/placeholder

@@ -0,0 +1 @@
+PLACE_HOLDER

doc/sphinx/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

doc/sphinx/conf.py

@@ -0,0 +1,54 @@
+# 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 = "Phoebus"
+copyright = "2024, Triad National Security"
+author = "The Phoebus Team"
+release = "1.0.0"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_multiversion",
+    "sphinx.ext.todo",
+    "sphinx_copybutton",
+    "sphinx_sitemap",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# 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".
+html_static_path = ["_static"]
+
+# configuration for sphinx_multiversion
+smv_remote_whitelist = r"^(origin)$"
+
+# Display todos by setting to True
+todo_include_todos = True
+
+# baseurl for sitemap
+html_baseurl = "https://lanl.github.io/phoebus"