Merge remote-tracking branch 'upstream/master'

arfc · Feb 7, 2022 · 715a876 · 715a876
2 parents 5339d2c + d82e4f4
commit 715a876
Show file tree

Hide file tree

Showing 37 changed files with 1,552 additions and 667 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -8,10 +8,10 @@ assignees: ''
 ---
 
 ## Expected behavior
-A clear and concise description of what you expected to happen.
+<!-- A clear and concise description of what you expected to happen. -->
 
 ## Describe the bug
-A clear and concise description of what the bug is.
+<!-- A clear and concise description of what the bug is. -->
 
 ## To Reproduce
 Steps to reproduce the behavior:
@@ -21,7 +21,7 @@ Steps to reproduce the behavior:
 4. 
 
 ## Supporting Informatioon
-If applicable, add program output with triple backticks, a gist of your output, or a screenshot to help explain your problem.
+<!-- If applicable, add program output with triple backticks, a gist of your output, or a screenshot to help explain your problem. -->
 
 ## System Specifications:
  <!-- At a minimum, include the SaltProc version and versions of software directly related to the bug-->

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -14,8 +14,10 @@
 - [ ] I have read the **CONTRIBUTING** document.
 - [ ] My code follows the code style of this project.
 - [ ] My change requires a change to the documentation.
-- [ ] I have updated the documentation accordingly.
-- [ ] I have added tests to cover my changes.
+  - [ ] I have updated the documentation accordingly.
+- [ ] My change is a source code change
+  - [ ] I have added/modified tests to cover my changes
+  - [ ] I have explained why my change does not require new/modified tests 
 - [ ] All new and existing tests passed.
   - [ ] CI tests pass
   - [ ] Local tests pass (including Serpent2 integration tests)

diff --git a/.github/workflows/cache-dependencies.yml b/.github/workflows/cache-dependencies.yml
@@ -4,12 +4,14 @@ name: Cache dependencies
 on:
   schedule:
     - cron: '0 9 * * 1' # run every monday @ 9AM
+  # enable worflow to be run manually
+  workflow_dispatch:
 
 env:
   CACHE_NUMBER: 0 
 
 jobs:
-  cache-dependencies:
+  cache-build-dependencies:
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -18,6 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
+## TESTING CACHE ##
 # Setup conda 
       - name: Set up conda
         uses: conda-incubator/setup-miniconda@v2
@@ -52,3 +55,43 @@ jobs:
 
       - name: Check packages
         run: conda list
+  cache-doc-dependencies:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v2
+
+## DOCUMENTATION CACHE ##
+      - name: Set up conda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge # mamba is faster than base conda
+          miniforge-version: latest
+          activate-environment: saltproc-doc-env
+          use-mamba: true
+          use-only-tar-bz2: true
+      - run: |
+          conda config --env --set pip_interop_enabled True
+
+# check for existing cache
+      - name: Set cache date
+        run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v2
+        id: dependencies-cache
+        with:
+          path: |
+            /usr/share/miniconda3/envs/saltproc-doc-env
+            ~/.cache/pip
+          key: depcache-${{ hashFiles('doc/doc-environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+
+# Install dependencies
+      - name: Update environment
+        run: mamba env update -n saltproc-doc-env -f doc/doc-environment.yml
+        if: steps.dependencies-cache.outputs.cache-hit != 'true'
+
+      - name: Check packages
+        run: conda list
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -2,12 +2,16 @@
 name: Deploy SaltProc docs
 
 on:
+  release:
+    type: [published]
   push:
     branches:
       - master 
     paths:
       - 'doc/**'
       - 'saltproc/**'
+  # enable worflow to be run manually
+  workflow_dispatch:
 
 env:
   CACHE_NUMBER: 0 #change to manually reset cache
@@ -22,14 +26,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
+        with:
+            fetch-depth: 0
 
 # Setup conda 
       - name: Set up conda
         uses: conda-incubator/setup-miniconda@v2
         with:
           miniforge-variant: Mambaforge # mamba is faster than base conda
           miniforge-version: latest
-          activate-environment: saltproc-env
+          activate-environment: saltproc-doc-env
           use-mamba: true
           use-only-tar-bz2: true
       - run: |
@@ -43,30 +49,26 @@ jobs:
         id: dependencies-cache
         with:
           path: |
-            /usr/share/miniconda3/envs/saltproc-env
+            /usr/share/miniconda3/envs/saltproc-doc-env
             ~/.cache/pip
-          key: depcache-${{ hashFiles('environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+          key: depcache-${{ hashFiles('doc/doc-environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
 
 # Install dependencies
       - name: Update environment
-        run: mamba env update -n saltproc-env -f environment.yml
+        run: mamba env update -n saltproc-doc-env -f doc/doc-environment.yml
         if: steps.dependencies-cache.outputs.cache-hit != 'true'
 
-      - name: Install SaltProc
-        run:  pip install .
-
       - name: Check packages
         run: conda list
 
       - name: Build Sphinx Documentation
         run: |
-          cd doc
-          sphinx-apidoc --separate --force --output-dir=src/ ../saltproc
-          make clean
-          make html
+            sphinx-multiversion doc doc/_build/html
+            cp doc/redirect.html doc/_build/html/index.html
 
       - name: Deploy documentation to gh-pages branch
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./doc/_build/html
+          commit_message: "update docs at commit: ${{ github.event.head_commit.message }}"
diff --git a/.github/workflows/test-saltproc.yml b/.github/workflows/test-saltproc.yml
@@ -3,11 +3,15 @@ name: Test SaltProc
 
 on:
   push:
+    paths:
+      - 'saltproc/**'
+      - 'saltproc/tests/**'
   pull_request:
-  workflow_dispatch:
   workflow_run:
     workflows: ["Cache dependencies"]
     types: [completed]
+  # enable worflow to be run manually
+  workflow_dispatch:
 
 env:
   CACHE_NUMBER: 0 #change to manually reset cache

diff --git a/README.md b/README.md
@@ -24,19 +24,19 @@ Detailed installation instructions can be found in the
 
 The documentation for SaltProc can be found at
 [arfc.github.io/saltproc/](http://arfc.github.io/saltproc/).
-Additionally, the entire contents of that
-website can be built from the doc directory in the source code using the
-following steps
+The entire contents of that
+website can be built from the `doc` directory in the repositiory using the following steps with the [`conda`](https://docs.conda.io/en/latest/) tool:
 
-1. `pip install sphinx`
-2. `pip install sphinx_rtd_theme`.
-3. `cd doc/`
-4. `sphinx-apidoc --separate --force --output-dir=src/ ../saltproc`
-5. `make clean`
-6. `make html`
+1. `conda env create -f doc/doc-environment.yml`
+2. `cd doc/`
+3. `make clean`
+4. `make html`
 
 After these steps, the website will be found in `saltproc/doc/_build/html`.
 
+_Note_: We recommend using [`mamba`](https://github.com/mamba-org/mamba) CLI tool to install packages quickly. SaltProc has a compltex package dependency structure which can result is long environment solve times in the default ``conda`` solver. ``mamba`` is a reimplementation of ``conda`` in ``C++`` and we have found it is significantly faster.
+
+
 ## License
 
 The license for this work can be found

diff --git a/doc/_templates/versions.html b/doc/_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 %}
diff --git a/doc/conf.py b/doc/conf.py
@@ -17,17 +17,43 @@
 import sphinx_rtd_theme
 sys.path.append(os.path.abspath('../'))
 sys.path.append(os.path.abspath('../saltproc'))
+# autopep8 will make a stink about this but
+# we need to have saltproc on ouy syspath
+# before we can import it
+from saltproc.version import __version__
+
 
 # -- Project information -----------------------------------------------------
 
 project = u'Saltproc'
-copyright = u'2018, Andrei Rykhlevskii, Jin Whan Bae, Kathryn D. Huff'
-author = u'Andrei Rykhlevskii, Jin Whan Bae, Kathryn D. Huff'
+author = u'Oleksandr Yardas, Andrei Rykhlevskii,\
+    Jin Whan Bae, Kathryn D. Huff'
+copyright = u'2021, ' + author
 
 # The short X.Y version
-version = ''
+version = __version__
 # The full version, including alpha/beta/rc tags
-release = ''
+release = __version__
+
+# -- sphinx-multiversion configuration ---------------------------------------
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r'^v\d[.][^12][.]\d.*$'
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r'^(master)*$'
+
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = r'^(origin|upstream)$'
+
+# Pattern for released versions
+smv_released_pattern = r'^tags/.*$'
+
+# Format for versioned output directories inside the build directory
+smv_outputdir_format = '{ref.name}'
+
+# Determines whether remote or local git branches/tags are preferred
+# if their output dirs conflict
+smv_prefer_remote_refs = True
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,6 +66,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinxcontrib.apidoc',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
@@ -49,7 +76,13 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-]
+    'sphinx_multiversion']
+
+# apidoc settings
+apidoc_module_dir = '../saltproc/'
+apidoc_output_dir = 'src/'
+apidoc_excluded_paths = []
+apidoc_separate_modules = True
 
 # Napoleon settings
 napoleon_google_docstring = False

diff --git a/doc/doc-environment.yml b/doc/doc-environment.yml
@@ -0,0 +1,15 @@
+name: saltproc-doc-env
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - pyne>=0.5.11
+  - numpy>=1.14.0
+  - pytables
+  - networkx
+  - pydotplus
+  - sphinx
+  - sphinx_rtd_theme
+  - pip:
+      - sphinx-multiversion
+      - sphinxcontrib-apidoc