Merge branch 'release/v0.12.0' #155

.github/workflows/python-package.yml

@@ -10,22 +10,26 @@ on:
       - '**.png'
       - 'img/*'
       - 'LICENSE'
+      - 'docs/**'
+      - '**.rst'
   pull_request:
     paths-ignore:
       - '**.md'
       - '**.png'
       - 'img/*'
       - 'LICENSE'
+      - 'docs/**'
+      - '**.rst'
 
 jobs:
   build:
 
     runs-on: ubuntu-latest
     # See: https://github.com/marketplace/actions/skip-based-on-commit-message
-    if: "!contains(github.event.head_commit.message, 'ci skip') || !contains(github.event.head_commit.message, 'skip ci')"
+    if: "!contains(github.event.head_commit.message, 'docs only')"
     strategy:
       matrix:
-        python-version: ['3.7', '3.8']
+        python-version: ['3.7', '3.8', '3.9']
 
     steps:
     - uses: actions/checkout@v2

.github/workflows/sphinx-build.yml

@@ -0,0 +1,24 @@
+name: "Sphinx Docs Check"
+on:
+  push:
+    paths:
+    - 'docs/**'
+    - 'requiam_csv/**'
+    - '.github/workflows/sphinx*yml'
+  pull_request:
+    paths:
+    - 'docs/**'
+    - 'requiam_csv/**'
+    - '.github/workflows/sphinx*yml'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout requiam_csv
+      uses: actions/checkout@v2
+    - name: Sphinx build
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"

.gitignore

@@ -135,4 +135,4 @@ venv.bak/
 dmypy.json
 
 # Pyre type checker
-.pyre/
+.pyre/

README.md

@@ -1,9 +1,11 @@
 # ![CSV Generation Tool for ReQUIAM](img/ReQUIAM_csv_full.png)
 
-[![GitHub build](https://github.com/ualibraries/ReQUIAM_csv/workflows/Python%20package/badge.svg)](https://github.com/ualibraries/ReQUIAM_csv/actions?query=workflow%3A%22Python+package%22)
-![GitHub top language](https://img.shields.io/github/languages/top/ualibraries/ReQUIAM_csv)
-![GitHub release (latest by date)](https://img.shields.io/github/v/release/ualibraries/ReQUIAM_csv)
-![GitHub](https://img.shields.io/github/license/ualibraries/ReQUIAM_csv?color=blue)
+[![GitHub Workflow Status (master)](https://img.shields.io/github/workflow/status/UAL-ODIS/ReQUIAM_csv/Python%20package/master?color=blue&label=build%20%28master%29&logo=github)](https://github.com/UAL-ODIS/ReQUIAM_csv/actions?query=workflow%3A%22Python+package%22+branch%3Amaster)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/UAL-ODIS/ReQUIAM_csv/Python%20package?color=blue&label=build%20%28latest%29&logo=github)](https://github.com/UAL-ODIS/ReQUIAM_csv/actions?query=workflow%3A%22Python+package%22)
+[![docs](https://img.shields.io/github/workflow/status/UAL-ODIS/ReQUIAM_csv/Sphinx%20Docs%20Check?label=docs&color=blue)](https://github.com/UAL-ODIS/ReQUIAM_csv/actions?query=workflow%3A%22Sphinx+Docs+Check%22)
+![GitHub top language](https://img.shields.io/github/languages/top/UAL-ODIS/ReQUIAM_csv)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/UAL-ODIS/ReQUIAM_csv)
+![GitHub](https://img.shields.io/github/license/UAL-ODIS/ReQUIAM_csv?color=blue)
 
 - [Overview](#overview)
 - [Getting Started](#getting-started)
@@ -56,7 +58,7 @@ These instructions will have the code running on your local or virtual machine.
 ### Requirements
 
 You will need the following to have a working copy of this software. See [installation](#installation-instructions) steps:
-1. Python (3.7.5)
+1. Python (>=3.7.9)
 2. [`numpy`](https://numpy.org/doc/) ([1.18.0](https://numpy.org/doc/1.18/))
 3. [`pandas`](https://pandas.pydata.org/) ([0.25.3](https://pandas.pydata.org/pandas-docs/version/0.25.3/))
 
@@ -65,14 +67,14 @@ You will need the following to have a working copy of this software. See [instal
 
 #### Python and setting up a `conda` environment
 
-First, install a working version of Python (v3.7.5).  We recommend using the
+First, install a working version of Python (>=3.7.9).  We recommend using the
 [Anaconda](https://www.anaconda.com/distribution/) package installer.
 
 After you have Anaconda installed, you will want to create a separate `conda` environment
 and activate it:
 
 ```
-$ (sudo) conda create -n rsh_themes python=3.7.5
+$ (sudo) conda create -n rsh_themes python=3.7
 $ conda activate rsh_themes
 ```
 
@@ -98,7 +100,7 @@ You can confirm installation via `conda list`
 (rsh_themes) $ conda list requiam_csv
 ```
 
-You should see that the version is `0.11.1`.
+You should see that the version is `0.12.0`.
 
 
 ### Configuration Settings

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx>=3.0
+sphinx-rtd-theme==0.5.1
+sphinx-autodoc-typehints==1.11.1
+numpy==1.19.5
+pandas==1.2.1

docs/source/authors.rst

@@ -0,0 +1,11 @@
+Authors
+=======
+
+-  Chun Ly, Ph.D. (`@astrochun <http://www.github.com/astrochun>`__) -
+   `University of Arizona Libraries <https://github.com/ualibraries>`__,
+   `Office of Digital Innovation and
+   Stewardship <https://github.com/UAL-ODIS>`__
+
+See also the list of
+`contributors <https://github.com/UAL-ODIS/ReQUIAM_csv/contributors>`__
+who participated in this project.

docs/source/conf.py

@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import sphinx_rtd_theme
+import sphinx_autodoc_typehints
+sys.path.insert(0, os.path.abspath('../../'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'ReQUIAM_csv'
+copyright = '2021, University of Arizona Libraries'
+author = 'Chun Ly'
+
+# The full version, including alpha/beta/rc tags
+release = '0.12.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]   
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/execution.rst

@@ -0,0 +1,27 @@
+Execution
+=========
+
+By default, the script does a “dry run.” To execute the script and
+override the main CSV file (data/research_themes.csv), include the
+``execute`` argument
+
+::
+
+   (rsh_themes) $ python requiam_csv/script_run --execute
+
+.. _workflow:
+
+Workflow
+--------
+
+The recommended workflow to commit changes on the main CSV file is as
+follows:
+
+1. First, switch to ``develop`` branch: ``git checkout develop``
+2. Conduct a dry run execution
+3. Compare the two CSV files: ‘data/research_themes.csv’ and ‘data/dry_run.csv’
+4. If the changes are what you expect, conduct the full execution
+5. Update the version number in README.md, ``__init__.py``, and setup.py
+6. Perform a ``git add`` and ``git commit`` for ‘data/research_themes.csv’ and the above files to ``develop``
+7. Create a pull request `here <https://github.com/UAL-ODIS/ReQUIAM_csv/compare/develop?expand=1>`__
+8. Update your local git repository with ``git pull --all``

docs/source/getting_started.rst

@@ -0,0 +1,78 @@
+Getting Started
+===============
+
+These instructions will have the code running on your local or virtual
+machine.
+
+Requirements
+------------
+
+You will need the following to have a working copy of this software. See
+`installation <#installation-instructions>`__ steps:
+
+1. Python (>=3.7.9)
+2. `numpy <https://numpy.org/doc/>`__ (`1.18.0 <https://numpy.org/doc/1.18/>`__)
+3. `pandas <https://pandas.pydata.org/>`__ (`0.25.3 <https://pandas.pydata.org/pandas-docs/version/0.25.3/>`__)
+
+Installation Instructions
+-------------------------
+
+Python and setting up a ``conda`` environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, install a working version of Python (>=3.7.9). We recommend using
+the `Anaconda <https://www.anaconda.com/distribution/>`__ package
+installer.
+
+After you have Anaconda installed, you will want to create a separate
+``conda`` environment and activate it:
+
+::
+
+   $ (sudo) conda create -n rsh_themes python=3.7
+   $ conda activate rsh_themes
+
+Next, clone this repository into a parent folder:
+
+::
+
+   (rsh_themes) $ cd /path/to/parent/folder
+   (rsh_themes) $ git clone https://github.com/UAL-ODIS/ReQUIAM_csv.git
+
+With the activated ``conda`` environment, you can install with the
+``setup.py`` script:
+
+::
+
+   (rsh_themes) $ cd /path/to/parent/folder/ReQUIAM_csv
+   (rsh_themes) $ (sudo) python setup.py develop
+
+This will automatically installed the required ``numpy`` and ``pandas``
+packages.
+
+You can confirm installation via ``conda list``
+
+::
+
+   (rsh_themes) $ conda list requiam_csv
+
+You should see that the version is ``0.12.0``.
+
+Configuration Settings
+----------------------
+
+Configuration settings are specified through the
+`default.ini <https://github.com/UAL-ODIS/ReQUIAM_csv/blob/master/requiam_csv/default.ini>`__ file. These settings
+include the Google Sheet information and CSV file names (do **not**
+change as this will break ReQUIAM).
+
+Testing Installation
+--------------------
+
+To test the installation and create a temporary CSV file that does not
+affect the main CSV file, the following command will run and generate a
+file called ``dry_run.csv``:
+
+::
+
+   (rsh_themes) $ python requiam_csv/script_run