Merge pull request #2 from JGCRI/dev

Dev

.github/workflows/build.yml

@@ -1,14 +1,21 @@
 name: build
 
-on: [push, pull_request]
+on: 
+    push:
+        branches:
+          - main
+          - dev
+    pull_request:
+        branches:
+          - main
 
 jobs:
   build:
       runs-on: ${{ matrix.os }}
 
       strategy:
         matrix:
-          os: [ubuntu-latest]
+          os: [ubuntu-latest, windows-latest, macos-latest]
 
       env:
         OS: ${{ matrix.os }}
@@ -26,9 +33,5 @@ jobs:
         - name: Install dependencies
           run: |
             python -m pip install --upgrade pip
-            python setup.py install
-        - name: Test and generate coverage report on Linux
-          run: |
-            pip install pytest
-            pip install pytest-cov
-            pytest --cov=./ --cov-report=xml
+            pip install -r requirements.txt
+            python setup.py install

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: "docs"
+
+on: 
+    push:
+        branches:
+          - main
+          - dev
+    pull_request:
+        branches:
+          - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Install latex
+      run: |
+        sudo apt-get update -y && sudo apt-get install -y texlive-latex-extra dvipng
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+    - name: Update pip and install python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+    - name: Build html docs
+      working-directory: 'docs/'
+      run: |
+        make html
+    - name: Deploy
+      uses: JamesIves/github-pages-deploy-action@4.1.4
+      with:
+        branch: gh-pages # The branch the action should deploy to.
+        folder: docs/build/html # The folder the action should deploy. 
+

.github/workflows/draft-pdf.yml

@@ -1,4 +1,13 @@
-on: [push]
+name: "paper"
+
+on: 
+    push:
+        branches:
+          - main
+          - dev
+    pull_request:
+        branches:
+          - main
 
 jobs:
   paper:

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: "tests"
+
+on: 
+    push:
+        branches:
+          - main
+          - dev
+    pull_request:
+        branches:
+          - main
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+    - name: Test with pytest
+      run: |
+        pip install pytest
+        pip install pytest-cov
+        pytest --cov
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3

.gitignore

@@ -133,3 +133,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Others
+downloaded_data/

README.md

@@ -1,132 +1,120 @@
-[![build](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml) 
+[![build](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml)
+[![docs](https://github.com/JGCRI/pytemplate/actions/workflows/docs.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/docs.yml)
+[![tests](https://github.com/JGCRI/pytemplate/actions/workflows/test.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/JGCRI/pytemplate/branch/main/graph/badge.svg?token=2EWDAQI07B)](https://codecov.io/gh/JGCRI/pytemplate)
 
-## pytemplate
+# Introduction
 
-A template for a basic Python package with CI via GitHub actions and a JOSS paper template and action
+`pytemplate` is a template for creating a basic Python package with Continuous Integration (CI) via GitHub actions in the following steps:
 
-### Using this template
+<br>
+<br>
 
-Some version of the following, starting with the [Purpose](#purpose) section of this README, should be included in the README of your package.  The rest of this [Using this template](#using-this-template) section can be removed after you read it.
+[![pytemplate_build_your_own_package](extras/pytemplate_build_your_own_package.png)](https://raw.githubusercontent.com/JGCRI/pytemplate/dev/extras/pytemplate_build_your_own_package.png)
 
-#### Building your Python package
+<br>
+<br>
 
-The following are things to modify to make your Python package work for you:
+The folder structure is as shown below:
 
-- Change the version of your package in `pytemplate/__init__.py` which gets called in your `setup.py` file
-- I like to start by installing my package in `develop` model in a clean virtual environment.  You can do this a bunch of ways depending on your preferences. After building my clean virutal environment, I navigate to the root of my cloned directory and run `python setup.py develop`.  Running in develop mode allows you to make changes to your package and execute them on the fly without having to reinstall it everytime.  
-- You should now be able to open the Python prompt that you have your virtal environment built in and execute `import pytemplate` successfully.
+<br>
+<br>
 
+[![pytemplate_package_structure](extras/pytemplate_package_structure.png)](https://raw.githubusercontent.com/JGCRI/pytemplate/dev/extras/pytemplate_package_structure.png)
 
-#### Setting up your quickstarter Jupyter notebook
+<br>
+<br>
 
-Assuming that you have your package and Jupyter installed, you can use the quickstarter notebook as a way to introduce folks to the key functionality of your package.  
+# 1 Clone or "Use this template"
 
-You can do the following to link your virtual environment to your Jupyter notebook kernel:
+Navigate directly to https://github.com/JGCRI/pytemplate, click the shiny green button that says `Use this template` and be on your way.
 
-- Install `ipykernel` in your virtual environment via:
+You can also clone the template to view the files locally and then copy into your own repo as needed:
 
-    ```bash
-    pip install ipykernel
-    ```
-    and run the following:
-    ```bash
-    ipython kernel install --name "<my-virtual-environment-name"
-    ```
+```bash
+git clone https://github.com/JGCRI/pytemplate.git
+```
 
-    At this point, you should be able to select your virtual environment within your Jupyter Lab environment.
+# 2 Update Package Information
 
-    **NOTE**:  If you make changes to the source code of your package, you will need to restart the Jupyter kernel to have the change take effect in your Jupyter notebook.
+Update your information (package name and other details) in the following files:
 
-#### Building your docs
+- README.md
+- setup.py
+- LICENSE
+- pytemplate (Rename this folder to your new package name)
 
-To start install the following in your Python virutal environment:
+# 3 Update Package Modules
 
-```bash
-pip install sphinx
-pip install autodoc
-```
+This is where you write the main code for your model. We have include some key modules and tests. You should write tests for all your modules as you develop them.
 
-There is no need to initialize Sphinx since I have included prebuilt directories.  However, if you want to know how to do this yourself, you can look up how to run `sphinx-quickstart` from within a prebuild `docs` directory.
+- pytemplate\model.py (This is your main model class. Update all module names as modules are updated)
+- pytemplate\get_data.py (Update the path to your test data)
+- pytemplate\read_config.py (Used to read a configuration file with model settings)
+- pytemplate\read_data.py (Used to read data files for your model)
+- pytemplate\method.py (This is where you do your main model operations. You can write multiple methods within this file or if you have many methods you can group them into separate files e.g. spatial_downscaling.py, temporal_downscaling.py)
+- pytemplate\logger.py (This method starts the logger and is called in model.py. After this is loaded you can log all comments, errors and excution times throughout your code by using the logging module.)
+- pytemplate\diagnsotics.py (Update this to write your diagnostic scripts that test how various modules are performing.)
+- pytemplate\clean_up.py (Update this script to delete unecessary files, clean up memory and close out the model.)
 
-All of the documentation is contained within the `docs` directory.  This directory contains the following:
+# 4 Update Tests
 
-- `Makefile`:  To generate the `build` directory and it's contents for the website for Unix
-- `make.bat`:  To generate the `build` directory and it's contents for the website for Windows
-- `.nojekyll`:  Used when we generate our documentation website via GitHub Pages to ensure Jekyll is not used.
-- `source`:  Directory containing all information to build the website.  This is what is modified by you the user.  All documentation is built using ReStructuredText (.rst).
-    - `conf.py`:  The Python file that controls how your documentation is built.
-    - `index.rst`:  The blueprint of your website.
-    - The following were generated by running the Sphinx autodoc tool to build an API documentation of the package from the docstrings for each class, method, and function:  `modules.rst`, `pytemplate.rst`, `pytemplate.tests.rst`.  These were generated by running:
-    ```bash
-    sphinx-apidoc -f -o source/ ../pytemplate/
-    ```
+We provide a sample test file that should be updated as you add in new modules and classes. These tests are linked to the GitHub Action so that everytime you push any changes your tests are executed. The GitHub action also links to codecoverage so that you know how much of your code is covered by the tests you have written. You should aim to keep this percentage to above 70%.
 
-To generate the documentation website files run the following from the `docs` directory if on a Mac or Linux maching (use the `make.bat` for Windows):
+- pytemplate\tests\test_package.py (Update package and module names. Make sure to update tests as you new modules and classes)
 
-```bash
-make html
-```
 
-This will build the website here:  `docs/build/html`  You can open this locally by double-clicking the `index.html` file.  Ultimately, the contents of the `docs/build/html` directory will be hosted on a separate `gh-pages` branch as we only want to keep the source docs in the code branches.  To setup a webpage after building your docs, do the following:
+# 5 Update Package Documentation
 
-- Create a branch named `gh-pages` from what you have on `main`
-- In your GitHub repo, navigate to `Settings` -> `Pages` and ensure that `Source` is set to `Deploy from branch` and that `gh-pages` is selected as the branch and that `/root` is the target directory.
-- Copy the `docs/build/html` directory somewhere else on your machine (e.g., Desktop)
-- Pull your new branch to your local repo via `git pull --all`, navigate to the root directory of your repository, and change branches to `gh-pages` (e.g., `git checkout gh-pages`)
-- Remove everything from your repo when on the `gh-pages` branch.
-- Copy the contents of the `html` directory you copied into the repo.
-- Add an empty file named `.nojekyll` to the root directory with the HTML contents.
-- Add, commit, and push this to `gh-pages`.
-- Change directories back to `main` or your working branch.
+Update each of the following files to generate clean, clear documentation. When you push your changes to github the github actions described in the next section will automatically build the documentation page online for you. An example for this repo is available at: https://jgcri.github.io/pytemplate/. 
 
-If you navigate back to `Settings` -> `Pages` you will now see your web address that has been deployed.  This repos is:  https://jgcri.github.io/pytemplate/
-Copy this address and navigate back the main GitHub repo page (e.g., https://github.com/JGCRI/pytemplate).  Click the gear in the `About` section in the top right of your page, paste in the link to your webpage, and click `Save changes`.
+- docs\source\conf.py
+- docs\source\contributing.rst
+- docs\source\getting_started.rst
+- docs\source\index.rst
+- docs\source\license.rst
+- docs\source\modules.rst
+- docs\source\tests.rst
+- docs\source\user_guide.rst
 
-You now have a live documentation web page!  You can build custom sections that you can link to in the main README (these now only contain links to Goggle).
+Once your GitHub action for docs is complete (see section 6 GitHub Actions) you need the following steps to get your documentation page live online:
 
-#### Your GitHub Actions
+<br>
+<br>
 
-Your tests in the package will run via continuous integration from the `build.yml` action.  This is linked to the badge in your README.
+[![pytemplate_package_structure](extras/pytemplate_activate_docs.png)](https://raw.githubusercontent.com/JGCRI/pytemplate/dev/extras/pytemplate_activate_docs.png)
 
-#### Modifying your JOSS paper
+<br>
+<br>
 
-I put a sample JOSS paper, bibliography, and figure in a directory named `paper` in the root.  This gets compiled to a PDF file so you can check formatting via this GitHub action:  `.github/workflows/draft-pdf.yml which creates a PDF as an artifact that you can download in the action.
-This paper includes sample referencing as well.
+# 6 Github Actions
 
-### Purpose
+The final piece is to check your GitHub actions for continuous integration. These actions have been written so they are trigger everytime you push to main or execute a pull request to main. There are four GitHub actions included with this package as follows: 
 
-`pytemplate` was created to make life easier when creating a new Python package.  It comes prebuilt with the following:
-- A Python package
-- A prebuilt example test suite
-- A sample documentation directory and process using Sphinx
-- A sample Journal of Open Source Software (JOSS) paper template directory
-- A GitHub Action workflow for continous integration (CI)
-- A GitHub Action workflow for building a PDF from the JOSS paper directory
-- A quickstarter Jupyter notebook to introduce your package
-- This README which contains specifics that are needed
+- .github\workflows\build.yml (Tests if package builds on windows, macos, ubuntu)
+- .github\workflows\docs.yml (Automatically builds you docs from the docs folder)
+- .github\workflows\draft-pdf.yml (Automatically builds a JOSS version of a software paper from the paper folder. You can update paper.md file if you plan to publish your model.)
+- .github\workflows\test.yml (Runs your tests and check what percentage is covered on codecov. You will need to connect your repository to codecoverage for this to work as shown below.)
 
-### Installation
+<br>
+<br>
 
-Since this package is a demo and contains no real code that produces something useful, you can simply use this repository to build your own by selecting it as a `Template` when building a new repository.  Then you can modify the contents to suit your needs.  You can also navigate directly to https://github.com/JGCRI/pytemplate, click the shiny green button that says `Use this template` and be on your way.
+[![pytemplate_codecov](extras/pytemplate_codecov.png)](https://raw.githubusercontent.com/JGCRI/pytemplate/dev/extras/pytemplate_codecov.png)
 
-However, if you want to play around with this package to get used to how things are arranged, you can clone it locally via:
+<br>
+<br>
 
-```bash
-git clone https://github.com/JGCRI/pytemplate.git
-```
+The final step is to add your badges to your repository as follows. Simply replace "pytemplate" with your own repo name in the following three badges and then paste these at the top of the README.md file and push:
 
-### Check out a quickstart tutorial to run `pytemplate`
-
-Run `pytemplate` using the quickstart tutorial:  [Quickstart Tutorial](www.google.com)
+```
+[![build](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/build.yml)
+[![docs](https://github.com/JGCRI/pytemplate/actions/workflows/docs.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/docs.yml)
+[![tests](https://github.com/JGCRI/pytemplate/actions/workflows/test.yml/badge.svg)](https://github.com/JGCRI/pytemplate/actions/workflows/test.yml)
+```
+For the codecoverage badge use the Markdown badge you copied from codecov as shown in the final step above.
 
-### Getting started
 
-New to `pytemplate`?  Get familiar with what it is all about in our [Getting Started](www.google.com) docs!
 
-### How to contribute
 
-Whether you find a typo in the documentation, find a bug, or want to develop functionality that you think will make cerf more robust, you are welcome to contribute! See our [Contribution Guidelines](www.google.com)
 
-### API reference
 
-The reference guide contains a detailed description of the cerf API. The reference describes how the methods work and which parameters can be used. It assumes that you have an understanding of the key concepts. See [API Reference](www.google.com)

docs/source/acknowledgement.rst

@@ -0,0 +1,5 @@
+Acknowledgement
+===============
+
+The development of this software was supported by the US Department of Energy, Office of Science, as part of research in MultiSector Dynamics, Earth and Environmental System Modeling Program. The Pacific Northwest National Laboratory is operated for DOE by Battelle Memorial Institute under contract DE-AC05-76RL01830. The
+views and opinions expressed in this paper are those of the authors alone.

docs/source/conf.py

@@ -3,18 +3,37 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+
+# -- Initial Setup -----------------------------------------------------
+# 
+import sphinx_rtd_theme
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'pytemplate'
-copyright = '2022, I.M. Human'
-author = 'I.M. Human'
+copyright = 'JGCRI 2023'
+author = 'JGCRI'
 release = '0.0.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_rtd_theme',
+    'sphinx_panels',
+    'sphinx-mathjax-offline'
+]
 
 templates_path = ['_templates']
 exclude_patterns = []
@@ -24,5 +43,5 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']