Merge pull request #407 from drewejohnson/fix-readme

DOC Update the main readme, release guide

Author: Andrew Johnson

README.rst

@@ -33,12 +33,10 @@ Installation
 
    $ python -m pip install --user --upgrade pip serpentTools
 
-
 For more detailed instructions, including operating-system specific
 instructions and building from source, see
 `Installation Guide <http://serpent-tools.readthedocs.io/en/latest/install.html>`_.
 
-
 Issues
 ======
 
@@ -51,25 +49,19 @@ References
 
 The Annals of Nuclear Energy article should be cited for all work
 using ``SERPENT``. If you are using this project, please considering
-citing with::
+citing with
 
-    Andrew Johnson, Dan Kotlyar, Stefano Terlizzi, and Gavin Ridley,
-    "`serpentTools: A Python Package for Expediting Analysis with
-    Serpent <https://doi.org/10.1080/00295639.2020.1723992>`_,"
-    *Nuc. Sci. Eng*, (in press) (2020).
+* Andrew Johnson, Dan Kotlyar, Stefano Terlizzi, and Gavin Ridley,
+  "`serpentTools: A Python Package for Expediting Analysis with
+  Serpent <https://doi.org/10.1080/00295639.2020.1723992>`_,"
+  *Nuc. Sci. Eng*, (in press) (2020).
 
 Also, let us know if you publish work using this package! We try and
-keep an up-to-date list of `works using serpentTools`_, and would be
+keep an up-to-date list of works using serpentTools [2]_, and would be
 happy to include more.
 
-If you want to refer to a specific version, follow the `Zenodo DOI 
-<https://doi.org/10.5281/zenodo.1301035>`_. This will resolve to the latest
-version, with links to earlier releases.
-
- .. _works using serpentTools: https://github.com/CORE-GATECH-GROUP/serpent-tools/wiki/Publications-using-serpentTools
-
-If you want to refer to a specific version, follow the `Zenodo DOI 
 .. [1] Leppanen, J. et al. (2015) "The Serpent Monte Carlo code: Status,
     development and applications in 2013." Ann. Nucl. Energy, `82 (2015) 142-150
     <http://www.sciencedirect.com/science/article/pii/S0306454914004095>`_
 
+.. [2] https://github.com/CORE-GATECH-GROUP/serpent-tools/wiki/Publications-using-serpentTools

docs/develop/git.rst

@@ -38,19 +38,19 @@ should be incremented prior to new releases with the following designation:
 Releases
 ========
 
-Releases should be done with `git tags <https://git-scm.com/docs/git-tag>`_ from the master branch 
-and then pushed to GitHub. 
-Annotated tags should be used and can be created with::
+Following a release, the following actions should be performed:
 
-    git tag -a <version>
-    git tag -s <version>
-    git tag -m <msg> <version>
+1. Archived and installable python files should be created
+2. Archived and installable python files should be uploaded to the
+   python package index, :term:`PyPI`
+3. The tag should be pushed to GitHub and marked as a release, including information
+   on the changes introduced in this release
 
-Pushing these tags to GitHub creates a new 
-`release <https://github.com/CORE-GATECH-GROUP/serpent-tools/releases>`_.
-If a message is used, the messages should be a brief message describing the changes on this tag.
-On the release page, a more detail list of changes, such as pull requests and issues closed, 
-should be listed.
+This section details changes and procedures that, if followed, will increase chances
+of a painless release.
+
+Updating the package version
+----------------------------
 
 Before and after a release, the project version number should be updated in the
 following places:
@@ -59,13 +59,52 @@ following places:
 2. ``serpentTools/__init__.py``
 3. ``docs/conf.py``
 
-Following a release, the following actions should be performed:
+The new version should be indicative of the changes introduced between this release
+and the previous release.
 
-1. Archived and installable python files should be created
-2. Archived and installable python files should be uploaded to the
-   `python package index <https://pypi.python.org/pypi>`_
-3. The tag should be pushed to GitHub and marked as a release, including information
-   on the changes introduced in this release
+Generating distributions
+------------------------
+
+The new distribution, that can be uploaded to :term:`PyPI`, can be
+generated with
+
+.. code:: sh
+
+   python setup.py sdist bdist_wheel
+
+This will produce a source distribution and binary python wheel in the ``dist``
+directory, each of the form ``dist/serpentTools-<version>.<extension>``.
+Before tagging and pushing releases to :term:`PyPI`, the distribution should be
+checked with
+
+.. code:: sh
+
+   twine check dist/serpentTools-<version>*
+
+:term:`twine` will check that the package is compatible with the standards set
+by :term:`PyPI` prior to uploading. Following a successful check, the distribution
+can be pushed to the package index using
+
+..code:: sh
+
+    twine upload dist/serpentTools-<version>*
+
+Tagging
+-------
+
+Releases should be done with `git tags <https://git-scm.com/docs/git-tag>`_ from the master branch 
+and then pushed to GitHub. 
+Annotated tags should be used and can be created with
+
+.. code:: sh
+
+    git tag -s <version>
+
+Pushing these tags to GitHub creates a new 
+`release <https://github.com/CORE-GATECH-GROUP/serpent-tools/releases>`_.
+If a message is used, the messages should be a brief message describing the changes on this tag.
+On the release page, a more detail list of changes, such as pull requests and issues closed, 
+should be listed.
 
 .. _dev-commitMessages:
 

docs/glossary.rst

@@ -69,6 +69,11 @@ Glossary
         Recommended tool for installing Python packages. More at
         `<https://pypi.org/project/pip/>`_
 
+    PyPI
+        Python package index. Where packages that can easily
+        be fetched and installed via :term:`pip` can be found.
+        `<https://pypi.org>`_
+
     pytest
         Fully featured python test runner. More at 
         `<https://pytest.org/en/latest/>`_
@@ -87,6 +92,9 @@ Glossary
         distribution and licensing of ``SERPENT`` can be found at
         `<http://montecarlo.vtt.fi>`_. 
 
+    twine
+        Python package for interacting with and uploading packages to :term:`PyPI`
+
     yaml
         Human-readable format used for configuration files in this
         project. For more information, see

setup.py

@@ -54,6 +54,7 @@ def getDataFiles():
     'description': ('A suite of parsers designed to make interacting with '
                     'SERPENT output files simple, scriptable, and flawless'),
     'long_description': longDesc,
+    'long_description_content_type': 'text/x-rst',
     'maintainer': 'Andrew Johnson',
     'maintainer_email': '[email protected]',
     'author': 'serpentTools developer team',