Skip to content

Commit

Permalink
Merge pull request #104 from yardasol/vc-docs
Browse files Browse the repository at this point in the history
Versioned documenation hosting
  • Loading branch information
munkm authored Jan 28, 2022
2 parents 41c658c + 9f31ce4 commit 66bbd90
Show file tree
Hide file tree
Showing 11 changed files with 200 additions and 44 deletions.
45 changes: 44 additions & 1 deletion .github/workflows/cache-dependencies.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -18,6 +20,7 @@ jobs:
steps:
- uses: actions/checkout@v2

## TESTING CACHE ##
# Setup conda
- name: Set up conda
uses: conda-incubator/setup-miniconda@v2
Expand Down Expand Up @@ -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
24 changes: 13 additions & 11 deletions .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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: |
Expand All @@ -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 }}"
6 changes: 5 additions & 1 deletion .github/workflows/test-saltproc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 27 additions & 0 deletions doc/_templates/versions.html
Original file line number Diff line number Diff line change
@@ -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 %}
43 changes: 38 additions & 5 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------------------
Expand All @@ -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',
Expand All @@ -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
Expand Down
15 changes: 15 additions & 0 deletions doc/doc-environment.yml
Original file line number Diff line number Diff line change
@@ -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
34 changes: 27 additions & 7 deletions doc/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]: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.

Expand Down
9 changes: 9 additions & 0 deletions doc/redirect.html
Original file line number Diff line number Diff line change
@@ -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>
6 changes: 4 additions & 2 deletions environment.yml
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 66bbd90

Please sign in to comment.