Merge pull request #115 from yardasol/doc-changelog

Doc changelog

.github/pull_request_template.md

@@ -21,6 +21,7 @@
 - [ ] All new and existing tests passed.
   - [ ] CI tests pass
   - [ ] Local tests pass (including Serpent2 integration tests)
+- [ ] I have recorded my changes in the changelog for the upcoming release
 
 ## Associated Issues and PRs
 <!--- Please note any issues or pull requests associated with this pull request -->

.github/workflows/deploy-docs.yml

@@ -5,8 +5,6 @@ on:
   release:
     type: [published]
   push:
-    branches:
-      - master 
     paths:
       - 'doc/**'
       - 'saltproc/**'

.github/workflows/next-release-minor.yml

@@ -0,0 +1,79 @@
+# Preamble
+name: Create next minor release 
+
+on:
+  release:
+    type: [published]
+  # enable worflow to be run manually
+  workflow_dispatch:
+
+jobs:
+  next-release-minor:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get most recent release version
+        run: |
+          echo "RELEASE_VERSION=$(gh api repos/${{ github.repository }}/tags --jq '.[0] | .name')" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Increment minor version
+        run: |
+          IFS='.' read -ra arr <<< ${{ env.RELEASE_VERSION }}
+          MINOR_VERSION=$((${arr[1]}+1))
+          arr[1]=$MINOR_VERSION
+          NEW_RELEASE_VERSION="${arr[0]}.${arr[1]}.${arr[2]}"
+          echo "NEW_RELEASE_VERSION="$NEW_RELEASE_VERSION >> $GITHUB_ENV
+
+      - name: Create a new release
+        run: |
+          gh api repos/${{ github.repository }}/releases \
+          -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \
+          -H "Accept: application/vnd.github.v3+json" \
+          -X POST \
+          -F name=${{ env.NEW_RELEASE_VERSION }} \
+          -F tag_name=${{ env.NEW_RELEASE_VERSION }} \
+          -F draft=true 
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+
+      - name: Create a new milestone.
+        run: |
+          gh api repos/${{ github.repository }}/milestones \
+          -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \
+          -H "Accept: application/vnd.github.v3+json" \
+          -X POST \
+          -F title=${{ env.NEW_RELEASE_VERSION }} 
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create new release notes
+        run: |
+          echo "Configure git"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          echo "Make edits to docfiles"
+          cp doc/releasenotes/template.rst doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst
+          sed -i "s/vx.x.x/${{ env.NEW_RELEASE_VERSION }}/g" doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst
+          sed -i "s/${{ env.RELEASE_VERSION }}/${{ env.NEW_RELEASE_VERSION }}\n  ${{ env.RELEASE_VERSION }}/g" doc/releasenotes/index.rst
+          echo "Make edits to version.py"
+          sed -i "s/_version_micro = *'*[0-9]*'/_version_micro = ''/g" saltproc/version.py
+          sed -i "s/_version_minor = *'*[0-9]*'/_version_minor = ${{ env.MINOR_VERSION }}/g" saltproc/version.py
+          sed -i "s/^# _version_extra = 'dev'/_version_extra = 'dev'/g" saltproc/version.py
+          sed -i "s/^_version_extra = ''# _version_extra = ''/g" saltproc/version.py
+          echo "Add, commit, and push changes"
+          git add doc/releasenotes/${{ env.NEW_RELEASE_VERSION }}.rst
+          git add doc/releasenotes/index.rst
+          git commit -am "created ${{ env.NEW_RELEASE_VERSION }} release notes"
+          git add saltproc/version.py 
+          git commit -am "updated version to ${{ env.NEW_RELEASE_VERSION }}-dev"
+          git push

.github/workflows/populate-releasenotes.yml

@@ -0,0 +1,54 @@
+# Preamble
+name: Populate SaltProc release notes
+
+on:
+  push:
+    paths:
+      - 'doc/releasenotes/v**.rst'
+  # enable worflow to be run manually
+  workflow_dispatch:
+
+jobs:
+  populate-releasenotes:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Add conda to system path
+        run: |
+          # $CONDA is an environment variable pointing to the root of the miniconda directory
+          echo $CONDA/bin >> $GITHUB_PATH
+
+      - name: install pandoc 
+        run: |
+          conda install -c conda-forge pandoc
+          pip install --upgrade pandoc
+
+      - name: Get most recent draft release version
+        run: |
+          echo "RELEASE_VERSION=$(gh api repos/${{ github.repository }}/releases --jq '.[0] | .name')" >> $GITHUB_ENV
+          echo "RELEASE_ID=$(gh api repos/${{ github.repository }}/releases --jq '.[0] | .id')" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Convert .rst to .md 
+        run: pandoc -s -o RELEASENOTES.md -f rst -t gfm doc/releasenotes/${{ env.RELEASE_VERSION }}.rst --columns 1000
+
+
+      - name: Populate the release description with RELEASENOTES.md
+        run: |
+          gh api repos/${{ github.repository }}/releases/${{ env.RELEASE_ID }} \
+          -H "Authorize: token ${{ secrets.GITHUB_TOKEN }}" \
+          -H "Accept: application/vnd.github.v3+json" \
+          -X PATCH \
+          -F body="$(cat RELEASENOTES.md)"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -1,3 +1,5 @@
+# Contributing
+
 ### Thanks for Your Help!
 
 Contributing is so kind of you. In SaltProc, all contributions, bug reports,
@@ -87,6 +89,9 @@ Please use the provided pull request template. In particular:
   - **Make sure the test suite passes** on your computer. To do so, run
     `py.test saltproc` in the repository directory. At a minumum, you must 
     run the tests requring serpent locally as they are not tested by our CI
+  - Describe your feature/change/fix in the release notes (located in `doc/releasenotes`)
+    for the currently in-development release version. Use the descriptive comments and
+    examples as reference.
   - Please reference relevant Github issues in your commit message using
     `GH1234` or `#1234`.
   - Changes should be PEP8 compatible [PEP8](http://www.python.org/dev/peps/pep-0008/).

doc/devguide/contributing.rst

@@ -0,0 +1,110 @@
+Contributing
+============
+
+Thanks for Your Help!
+---------------------
+
+Contributing is so kind of you. In SaltProc, all contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome.
+
+The `GitHub "issues" tab <https://github.com/arfc/saltproc/issues>`__ contains some issues labeled "Difficulty:1-Beginner". Those are open issues that would be a good quick way to get started. Browse them to see if you want to get started on one.
+
+Bug Reports
+~~~~~~~~~~~
+
+Is something in the code not working? Consider making a bug report! In particular:
+
+-  Please include a short but detailed, self-contained Python snippet or explanation for reproducing the problem.
+
+-  Explain what the expected behavior was, and what you saw instead.
+
+Feature Requests
+~~~~~~~~~~~~~~~~
+
+If you have an idea that could add to or improve SaltProc, and know how to implement it, consider making a Feature Request!
+
+Discussion
+~~~~~~~~~~
+
+If you
+
+-  have feedback or a feature idea that aren't concrete/focused enough to go into a Feature Request Issue
+-  want to show off cool work you have done with the software
+
+please use our `Discussions page <https://github.com/arfc/saltproc/discussions>`__!
+
+Instructions for setting up a development environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SaltProc is compatible with Python >=3.5. Anaconda is the recommended distribution to use to work on SAltProc; we will assume that if you want to use another distribution or your own set up, you can translate the instructions.
+
+You can download Anaconda at https://www.continuum.io/Downloads for the full install. You can also download a mini Anaconda install for a bare-bones install -- this is good for a build server or if you don't have much space. The mini Anaconda installs are available at https://conda.io/miniconda.html.
+
+Once your Anaconda package is installed and available, create a Python 3.6 environment in Anaconda --
+
+::
+
+   conda create -q -n saltproc-test-environment python=3.6 scipy numpy matplotlib pytest pytables flake8
+
+Each of these commands will take a bit of time -- give it a few minutes to download and install the packages and their dependences. Once complete, switch to each and install additional packages needed to run and test.
+
+Activate the 3.6 environment and install pyne, networkx and pydotplus
+
+::
+
+   source activate saltproc-test-environment
+   conda install -c conda-forge pyne networkx pydotplus
+
+Setup Serpent Monte Carlo code environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SaltProc assumes that Serpent directory is added in ``$PATH`` as follows:
+
+::
+
+   export PATH="/path/to/serpent/executable:$PATH"
+
+Run the tests
+^^^^^^^^^^^^^
+
+Tests are automatically detected and run with pytest. Start in the root directory where you have cloned the saltproc repository and run in development environment
+
+::
+
+   source active saltproc-test-environment
+   py.test saltproc
+
+Run style tests with flake8
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adherance to style checks in flake8 is encouraged though not strictly enforced. While you should not feel compelled to fix existing failures, please do not add additional flake8 issues.
+
+::
+
+   run flake8 from the root of the pyrk working directory to get all flake8 issues
+   run flake8 and provide a filename to just run checks on that file
+
+Pull Requests
+^^^^^^^^^^^^^
+
+Please use the provided pull request template. In particular:
+
+-  **Make sure the test suite passes** on your computer. To do so, run ``py.test saltproc`` in the repository directory. At a minumum, you must run the tests requring serpent locally as they are not tested by our CI
+-  Describe your feature/change/fix in the release notes (located in ``doc/releasenotes``) for the currently in-development release version. Use the descriptive comments and examples as reference.
+-  Please reference relevant Github issues in your commit message using ``GH1234`` or ``#1234``.
+-  Changes should be PEP8 compatible `PEP8 <http://www.python.org/dev/peps/pep-0008/>`__.
+-  Keep style fixes to a separate commit to make your PR more readable.
+-  Docstrings ideally follow the `sphinx autodoc <https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions>`__
+-  Write tests.
+-  When writing tests, please make sure they are in a ``tests`` directory.
+-  When you start working on a PR, start by creating a new branch pointing at the latest commit on github master.
+-  The SaltProc copyright policy is detailed in the `LICENSE <https://github.com/arfc/saltproc/blob/master/LICENSE>`__.
+
+More developer docs
+~~~~~~~~~~~~~~~~~~~
+
+-  We are working on it.
+
+Meta
+~~~~
+
+Note, this contributing file was adapted from the one at the `pandas <https://github.com/pydata/pandas>`__ repo. Thanks pandas!

doc/devguide/index.rst

@@ -0,0 +1,23 @@
+.. _devguide:
+
+=================
+Developer's Guide
+=================
+.. _git workflow: https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
+
+Welcome to the SaltProc developer's guide. Here you'll find
+all the information you need to be an efficient and effective contributor
+to SaltProc.
+
+.. note:: The SaltProc developer's guide is a work in progress. 
+   Information contained within may change, so make sure to check the 
+   release notes for updates!
+
+If you're new to software development, please familiarize yourself with the
+`git workflow`_ before getting started. We'll be using terminoigy
+in this developer's guide that relies on understanding it.
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing

doc/index.rst

@@ -32,6 +32,8 @@ Documentation
    installation
    examples
    src/index
+   releasenotes/index
+   devguide/index
    How to cite <https://github.com/arfc/saltproc/blob/master/CITATION.md>
 
 Indices and tables
@@ -69,6 +71,12 @@ Acknowledgment
 SaltProc uses `Shablona`_ template which is universal solution for small
 scientific python projects developed at University of Washington `eScience Insititute`_.
 
+`OpenMC's docpages`_ heavily inspired the strucutre and format for SaltProc's docpages.
+
+We make our versioned documentation using `sphinx-multiversion`_.
+
+.. _sphinx-multiversion: https://github.com/Holzhaus/sphinx-multiversion
+.. _OpenMC's docpages: https://docs.openmc.org/en/stable/index.html
 .. _Shablona: https://github.com/uwescience/shablona
 .. _eScience Insititute: https://escience.washington.edu
 

doc/releasenotes/index.rst

@@ -0,0 +1,11 @@
+.. _releasenotes:
+
+=============
+Release Notes
+=============
+
+.. toctree::
+  :maxdepth: 1
+
+  v0.4.0
+  v0.3.0