Refactor project README.md structure and Sphinx documentation

Adds changelog to README and Sphinx documentation. Adds contributing to README, edits install instructions. Adds copyright and license to documentation. Renames api.rst and models.rst files. Changes basin3d-core to basin3d reference in documentation. Changes setup.py. Moves items around in table of contents.

Closes #36

CHANGES.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Version 0.0.2
+Project Updates:   
+   + Enable Github Actions
+   + Temporarily freeze Pandas v1.1.5 due to NaN errors
+   + Handle empty data returns
+
+Install Updates:
+   + Issue #29, #7: Fix install commands
+
+Documentation Updates:
+   + Issue #26: Fix typos and errors in README
+   + Issue #27, 35: Fix basin3d reference and updates authors
+   + Issue #28: Update git clone link in README
+   + Issue #38: Add BASIN-3D concepts to documentation
+   + Issue #41: Fix autogenerated Sphinx documentation
+   + Remove prerequisites section in README
+   + Update license to the BASIN-3D license
+
+## Version 0.0.1
+Project Updates:
+   + Prepare version for open-source release

CONTRIBUTING.md

@@ -1,5 +1,83 @@
 ## How to contribute to basin3d
 
-* Steps for creating good issues or pull requests.
-* Links to external documentation, mailing lists, or a code of conduct.
-* Community and behavioral expectations.
+## Quick Links
+* [Documentation]()
+* [Issue Template: Bugs](.github/ISSUE_TEMPLATE/bug_report.md)
+* [Issue Template: New Feature](.github/ISSUE_TEMPLATE/feature_request.md)
+* [Pull Request Template](.github/pull_request_template.md)
+* [Code of Conduct](CODE_OF_CONDUCT.md)
+
+
+## Development Practices
+
+* basin3d uses the [GitFlow model](https://datasift.github.io/gitflow/IntroducingGitFlow.html) 
+  of branching and code versioning in git. 
+* Code development will be performed in a feature/development branch of the repo. Commits will not be made directly to the master branch of basin3d repo.  Developers will submit a pull request that is then merged by another team member, if another team member is available.
+* Each pull request should contain only related modifications to a feature or bug fix.  
+* Sensitive information (secret keys, usernames etc) and configuration data (e.g database host port) should not be checked into the repo.
+* A practice of rebasing with the main repo should be used rather than merge commits.  
+
+## Develop
+
+Setup virtualenv for development and testing purposes. All basin3d tests
+are in `tests/`.
+
+Create an Anaconda environment
+
+    $ conda create -y -n basin3d python=3.7
+
+Activate the new environment and prepare it for development
+
+	$ conda activate basin3d
+	$ conda develop -npf -n basin3d .
+
+Install  basin3d and its dependencies
+
+	$ pip install $(cat requirements.txt) pytest
+	$ pip install pytest-flake8 pytest-mypy pytest-cov sphinx PSphinxTheme
+	$ python setup.py develop
+
+Run the tests (mypy and flake8 tests executed by default)
+
+    $ pytest 
+     
+Run the tests with coverage
+
+    $ pytest --cov=basin3d
+     
+Run the tests with coverage ONLY
+
+    $ pytest --cov=basin3d tests
+
+
+## Documentation
+
+Sphinx is used to generate documentation. You first need to create a virtual environment for generating the docs.
+
+	$ conda activate basin3d
+	$ pip install -r docs/requirements.txt
+
+Generate the documentation
+
+	$ cd docs
+	$ make html
+
+Review the generated documentation
+
+	$ open _build/html/index.html
+
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. For the versions available, 
+see the [tags on this repository](https://github.com/BASIN-3D/basin3d/tags). 
+
+Workflow for tagging and building release:
+
+1. checkout the version to tag from `main`
+1. `$ git tag -a v[version]-[release] -m "Tagging release v[version]-[release]"`
+1. build distribution with `$ setup.py`
+1. `$ git push origin v[version]-[release]`
+
+## Questions
+Our preferred channels of communication are public. Please open a [new discussion topic](https://github.com/BASIN-3D/basin3d/discussions) on Github discussions

README.md

@@ -1,101 +1,49 @@
 # basin3d
-Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets.
-A data synthesis framework for earth science data.
+Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets. 
 
+![basin3d](https://user-images.githubusercontent.com/20212666/112556236-ff1a9b80-8d86-11eb-9009-25b658ce41e0.png)
 
-## Development Practices
+BASIN-3D is a software ecosystem that synthesizes diverse earth science data from a variety of remote data sources on-demand, without the need for storing data in a single database. It is designed to parse, translate, and synthesize diverse observations from well-curated repositories into standardized formats for scientific uses such as analysis and visualization.
 
-* basin3d uses the [GitFlow model](https://datasift.github.io/gitflow/IntroducingGitFlow.html) 
-  of branching and code versioning in git. 
-* Code development will be performed in a feature/development branch of the repo. Commits will not be made directly to the master branch of basin3d repo.  Developers will submit a pull request that is then merged by another team member, if another team member is available.
-* Each pull request should contain only related modifications to a feature or bug fix.  
-* Sensitive information (secret keys, usernames etc) and configuration data (e.g database host port) should not be checked into the repo.
-* A practice of rebasing with the main repo should be used rather than merge commits.  
+basin3d is the core BASIN-3D application that uses a generalized data synthesis model that applies across a variety of earth science observation types (hydrology, geochemistry, climate etc.). 
 
-## Getting Started
-
-### Get the code
-
-These instructions will get you a copy of the project up and running on your local machine for 
-development and testing purposes. 
-
-    $ git clone git@github.com:BASIN-3D/basin3d.git
-    $ cd basin3d
-
-## Develop
-Setup virtualenv for development and testing purposes. All basin3d tests
-are in `tests/`.
-
-Create an Anaconda environment
-
-    $ conda create -y -n basin3d python=3.7
-
-Activate the new environment and prepare it for development
-
-	$ conda activate basin3d
-	$ conda develop -npf -n basin3d .
-
-Install  basin3d and its dependencies
+basin3d has available plugins that can connect to specific data sources of interest, and map the data source vocabularies to the basin3d synthesis models.
 
-	$ pip install $(cat requirements.txt) pytest
-	$ pip install pytest-flake8 pytest-mypy pytest-cov sphinx PSphinxTheme
-	$ python setup.py develop
-
-Run the tests (mypy and flake8 tests executed by default)
 
-    $ pytest 
-     
-Run the tests with coverage
 
-    $ pytest --cov=basin3d
-     
-Run the tests with coverage ONLY
+## Getting Started
 
+### Install
 
-    $ pytest --cov=basin3d tests
-
-## Documentation
-Sphinx is used to generate documentation. You first need
-to create a virtual environment for generating the docs.
+Install a source distribution with pip:
 
-    $ conda activate basin3d
-    $ pip install -r docs/requirements.txt
+    $ pip install git+https://github.com/BASIN-3D/basin3d.git
 
-Generate the documentation
-
-    $ cd docs
-    $ make html
+Make sure your installation was successful:
 
-Review the generated documentation
+    $ python
+    >>> import basin3d
+    >>>
 
-    $ open _build/html/index.html
-
-# Install
+## Documentation
 
-
-Install a source distribution with pip:
+See latest basin3d documentation [here](https://basin-3d.github.io/basin3d/html/index.html)
 
-    $ pip install basin3d-<version>.tar.gz
-
-To get started read the [setup](docs/getting_started.rst) documentation
 
-## Versioning
+## Contributing
 
-We use [SemVer](http://semver.org/) for versioning. For the versions available, 
-see the [tags on this repository](https://github.com/BASIN-3D/basin3d/tags). 
+If you’re interested in contributing to basin3d, check out out our [contributing guidelines](CONTRIBUTING.md). It will help explain why, what, and how to get started.
 
-Workflow for tagging and building release:
 
-1. checkout the version to tag from `main`
-1. `$ git tag -a v[version]-[release] -m "Tagging release v[version]-[release]"`
-1. build distribution with `$ setup.py`
-1. `$ git push origin v[version]-[release]`
+## Changelog
+See the [changelog](CHANGES.md) for a history of updates and changes to basin3d
 
 ## Authors
 
 * **Charuleka Varadharajan** - [LBL](https://eesa.lbl.gov/profiles/charuleka-varadharajan/)
 * **Valerie Hendrix**  - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss/staff/valerie-hendrix)
 * **Danielle Svehla Christianson** - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss/staff/danielle-christianson/)
+* **Catherine Wong**  - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss)
 
 
 ## Copyright
@@ -123,4 +71,4 @@ See [LICENSE](LICENSE) file for licensing details
 
 ## Acknowledgments
 
-This research is supported as part of the Watershed Function Scientific Focus Area funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research under Award no. DE-AC02-05CH11231. This research used resources of the National Energy Research Scientific Computing Center (NERSC), U.S. Department of Energy Office of Science User Facility operated under Contract No. DE-AC02-05CH11231. 
+This research is supported as part of the Watershed Function Scientific Focus Area funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research under Award no. DE-AC02-05CH11231. This research used resources of the National Energy Research Scientific Computing Center (NERSC), U.S. Department of Energy Office of Science User Facility operated under Contract No. DE-AC02-05CH11231. 

docs/_templates/indexcontent.html

@@ -16,7 +16,7 @@
          <span class="linkdescr">Instructions on installing BASIN-3D</span></p>
     </td><td width="50%">
 
-      <p class="biglink"><a class="biglink" href="{{ pathto("models") }}">Quick Guide</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("quick_guide") }}">Quick Guide</a><br/>
          <span class="linkdescr">Quick guide to basic functions</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("examples") }}">Examples</a><br/>
          <span class="linkdescr">Examples for using BASIN-3D</span></p>

docs/changelog.rst

@@ -1,2 +1,26 @@
 Change Log
-**********
+**********
+
+Version 0.0.2
+##############
+Project Updates:
+   + Enable Github Actions
+   + Temporarily freeze Pandas v1.1.5 due to NaN errors
+   + Handle empty data returns
+
+Install Updates:
+   + Issue #29, #7: Fix install commands
+
+Documentation Updates:
+   + Issue #26: Fix typos and errors in README
+   + Issue #27, 35: Fix basin3d reference and updates authors
+   + Issue #28: Update git clone link in README
+   + Issue #38: Add BASIN-3D concepts to documentation
+   + Issue #41: Fix autogenerated Sphinx documentation
+   + Remove prerequisites section in README
+   + Update license to the BASIN-3D license
+
+Version 0.0.1
+###############
+Project Updates:
+   + Prepare version for open-source release

docs/conf.py

@@ -19,7 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 # General information about the project.
-project = 'basin3d-core'
+project = 'basin3d'
 copyright = '2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory \n(subject to receipt of any required approvals from the U.S. Dept. of Energy).  All rights reserved.'
 author = 'Charuleka Varadharajan, Valerie Hendrix, Danielle Christianson'
 
@@ -33,7 +33,7 @@
 #
 # import os
 # import sys
-version = "0.0.1"
+version = "0.0.2"
 
 # -- General configuration ---------------------------------------------------
 
@@ -102,7 +102,7 @@
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
 # html_short_title = None
-html_short_title = 'basin3d-core {}'.format(version)
+html_short_title = 'basin3d {}'.format(version)
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -201,7 +201,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'basin3d-coredoc'
+htmlhelp_basename = 'basin3d-doc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -231,7 +231,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'basin3d-core-{}.tex'.format(version), 'basin3d-core Documentation',
+    (master_doc, 'basin3d-{}.tex'.format(version), 'basin3d Documentation',
      'Charuleka Varadharajan, Valerie Hendrix', 'manual'),
 ]
 
@@ -272,7 +272,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'basin-3d', 'basin3d-core Documentation',
+    (master_doc, 'basin-3d', 'basin3d Documentation',
      [author], 1)
 ]
 
@@ -287,8 +287,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'basin3d-core', 'basin3d-core Documentation',
-     author, 'basin3d-core', 'One line description of project.',
+    (master_doc, 'basin3d', 'basin3d Documentation',
+     author, 'basin3d', 'One line description of project.',
      'Miscellaneous'),
 ]
 

docs/copyright_notice.rst

@@ -1,2 +1,9 @@
 Copyright Notice
-****************
+****************
+
+
+Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets (BASIN-3D) Copyright (c) 2019, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
+
+If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.
+
+NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit other to do so.