Versioned documenation hosting

.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

.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 }}"

.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

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

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 %}

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

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

doc/installation.rst

@@ -18,28 +18,48 @@ SaltProc has the following dependencies:
 .. _PyTables: http://pytables.org
 .. _NetworkX: http://networkx.github.io
 .. _PyDotPlus: https://pydotplus.readthedocs.io/
+.. _pytest: https://docs.pytest.org
+.. _sphinx: https://www.sphinx-doc.org
+.. _sphinx-rtd-theme: https://sphinx-rtd-theme.readthedocs.io
 .. _matplotlib: http://matplotlib.org
 .. _ViTables: http://vitables.org
 .. _GitHub: http://github.com/arfc/saltproc
-
+.. _conda package manager: https://docs.conda.io/en/latest/
+.. _mamba: https://github.com/mamba-org/mamba
 
 Optional Depenendencies:
-
+  #. `pytest`_ (for testing)
+  #. `sphinx`_ and `sphinx-rtd-theme`_ (for building documentation)
   #. `matplotlib`_
   #. `ViTables`_
 
 
 
-Most of the dependencies are readily available through package managers.
-Once all the dependencies are installed, SaltProc can be installed.
 Clone the source from the SaltProc repository from `GitHub`_.
-Then run the following commands from the directory above cloned repository:
 
 .. code-block:: bash
 
-   git clone https://github.com/arfc/saltproc.git
+   git clone git@github.com:arfc/saltproc.git
+
+All of the dependencies are readily available through the `conda package manager`_.
+
+.. note:: We recommend using the `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.
+
+You can download the required ones using ``conda`` on the provided ``environment.yml``
+file in the repository:
+
+.. code-block:: bash
+
    cd saltproc/
-   python setup.py install --user
+   conda env create -f environment.yml
+
+Once all the dependencies are installed, SaltProc can be installed by
+running the following commands from within the cloned directory
+repository (assuming the `saltproc-env` environment is active):
+
+.. code-block:: bash
+
+   pip install .
 
 Please let us know if you run into trouble.
 

doc/redirect.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to master branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./master/index.html">
+    <link rel="canonical" href="https://arfc.github.io/saltproc/master/index.html">
+  </head>
+</html>

environment.yml

@@ -1,11 +1,13 @@
+name: saltproc-env
 channels:
   - conda-forge
+  - defaults
 dependencies:
   - pyne>=0.5.11
   - numpy>=1.14.0
   - pytables
   - networkx
   - pydotplus
   - pytest
-  - sphinx
-  - sphinx_rtd_theme
+  - pip:
+    - argparse==1.4.0