diff --git a/.github/workflows/cache-dependencies.yml b/.github/workflows/cache-dependencies.yml index ff2a9520c..d77ca8d62 100644 --- 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 index f8aac2d81..c091583cc 100644 --- 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,6 +26,8 @@ jobs: steps: - uses: actions/checkout@v2 + with: + fetch-depth: 0 # Setup conda - name: Set up conda @@ -29,7 +35,7 @@ jobs: 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 index bd1448762..c66303ff4 100644 --- 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 index 917df73af..eb49f4fc0 100644 --- 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 new file mode 100644 index 000000000..31a125789 --- /dev/null +++ b/doc/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} diff --git a/doc/conf.py b/doc/conf.py index 8b92d6bdc..cb132df80 100644 --- 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 new file mode 100644 index 000000000..eb15230d2 --- /dev/null +++ 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 diff --git a/doc/installation.rst b/doc/installation.rst index cda9562c6..faf7b7a79 100644 --- a/doc/installation.rst +++ b/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. diff --git a/doc/redirect.html b/doc/redirect.html new file mode 100644 index 000000000..b9e7244ac --- /dev/null +++ b/doc/redirect.html @@ -0,0 +1,9 @@ + + + + Redirecting to master branch + + + + + diff --git a/environment.yml b/environment.yml index e2516180d..3cb0f07e7 100644 --- a/environment.yml +++ b/environment.yml @@ -1,5 +1,7 @@ +name: saltproc-env channels: - conda-forge + - defaults dependencies: - pyne>=0.5.11 - numpy>=1.14.0 @@ -7,5 +9,5 @@ dependencies: - networkx - pydotplus - pytest - - sphinx - - sphinx_rtd_theme + - pip: + - argparse==1.4.0 diff --git a/saltproc/version.py b/saltproc/version.py index b4c09766e..bdfb452b8 100644 --- a/saltproc/version.py +++ b/saltproc/version.py @@ -4,9 +4,9 @@ # Format expected by setup.py and doc/source/conf.py: string of form "X.Y.Z" _version_major = 0 _version_minor = 3 -_version_micro = '' # use '' for first of series, number for 1 and above -# _version_extra = 'dev' -_version_extra = '0' # Uncomment this for full releases +_version_micro = '1' # use '' for first of series, number for 1 and above +_version_extra = 'dev' +# _version_extra = '0' # Uncomment this for full releases # Construct full version string from these. _ver = [_version_major, _version_minor] @@ -26,15 +26,16 @@ "Topic :: Scientific/Engineering"] # Description should be a one-liner: -description = "saltproc: the on-line reprocessing driver for SERPENT" +description = "saltproc: the on-line reprocessing driver for monte-carlo codes" # Long description will go up on the pypi page long_description = """ SaltProc ======== -Saltproc is a on-line reprocessing driver for SERPENT, which -runs SEPRENT from a given input file and parameters and performs -user-defined processing of the fuel salt by adding or removing -waste, fissile, and fertile streams. +SaltProc is an on-line reprocessing driver for monte-carlo +particle transport codes with depletion capabilites. SaltProc +runs the monte-carlo simulation from a given input file and +parameters, then performs user-defined processing of the fuel +salt by adding or removing waste, fissile, and fertile streams. License =======