Merge pull request #6 from haileyajohnson/docs

add documentation

Author: cdipsw

docs/dev_guide/contribute.md

@@ -0,0 +1,8 @@
+# Contributors guide
+- welcome contributions!
+- types on contributions
+- workflow
+
+## Setting up your git workflow
+
+## Tips & tricks

docs/dev_guide/index.md

@@ -0,0 +1,10 @@
+# Installing CDIPpy for development 
+This page contains instructions for CDIPpy users interested in customizing or contributiing to the library.
+
+## Download from source
+
+## Install with dev tools
+
+### testing
+
+### linting

docs/examples/index.md

@@ -0,0 +1,3 @@
+# 🚧 **UNDER CONSTRUCTION** 🚧
+
+This section is still being developed.

docs/index.md

@@ -0,0 +1,12 @@
+# CDIPpy
+CDIPpy is python library for navigating and accessing products provided by the [Coastal Data Information Program (CDIP)](https://cdip.ucsd.edu/m/about/) at Scripps Institution of Oceanography (SIO). It is a collection of utilities used within CDIP software operations that have useful potential for CDIP end-users as well.  
+
+A goal of publishing this library as an open source, contributable package is to foster closer collaboration between CDIP and the coommunity of users.
+
+## Navigating these docs
+The CDIP user community spans a brooad expertise and vastly different backgrounds in python development and usage - use the following guidelines to determine where to start in the documentation:  
+
+* If you a relatively comfortable working with python, visit the [Quickstart Guide](quickstart.md).
+* If you would like more explicit, step by step instructions for:
+    * Using `cdippy` as an end  user: see the [Users Guide](user_guide/index.md)
+    * Making changes to `cdippy`: see the [Developers Guide](dev_guide/index.md)

docs/quickstart.md

@@ -0,0 +1,47 @@
+## Installation
+To install CDIPpy locally, you can either  
+1.  clone the repository, navigate to the root directory, and run `pip install .` or   
+2. without cloning the repositorym, install from github: `pip install git+https://github.com/cdipsw/CDIPpy.git`
+
+🚧 **UNDER CONSTRUCTION** 🚧
+
+*TODO* add test snippet to check installation here
+
+---
+
+## Development
+To set up a development copy of CDIPpy, install the project form source using [`uv`](https://docs.astral.sh/uv/):  
+``` bash
+>>> pip install uv
+>>> uv venv
+>>> source activate .venv/bin/activate
+>>> uv pip install -e .[dev]
+```
+This creates a local, virtual environment at `./.venv`, and installs a version of CDIPpy that is editable (`-e`), along with several additional dev dependencies (`[dev]`).
+---
+
+### Testing
+This project uses python's built in `unittest` package. To run all tests: 
+~~~ bash
+>>> python -m unittest discover
+~~~
+To run with [coverage](https://coverage.readthedocs.io/en/7.8.2/):
+~~~ bash
+>>> coverage run -m unittest discover
+~~~
+To view the coverage report:
+~~~ bash
+>>> coverage report
+~~~
+---
+
+### Contributing
+Contributions are welcome and should be merged via pull request on the `main` branch from a forked repository. Before a PR can be merged, it needs to pass the following checks:
+
+* all tests passed
+* coverage >= threshhold
+* passes [`flake8`](https://flake8.pycqa.org/en/latest/) linter
+* there must be at least one reviewer approval
+* a CLA must be signed by the contributor, if this is their first commit
+
+If you do not wish you manually check the style for every commit, there is a pre-commit hook that can do it for you. After setting up CDIPpy for development, install the hook with: `pre-commit install`. The installed hook will auto-format the files in your commit with [`black`](https://black.readthedocs.io/en/stable/) and checked for any remaining format errors with `flake8`. 

docs/user_guide/data_access.md

@@ -0,0 +1,3 @@
+# 🚧 **UNDER CONSTRUCTION** 🚧
+
+This page is still being written.

docs/user_guide/index.md

@@ -0,0 +1,26 @@
+# CDIPpy end users guide
+This page contains instructions for CDIPpy users who just want to navigate, access, and visualize CDIP data products.
+
+## Installation
+There are few options for installing `CDIPpy`:
+
+1) Install from PyPI (easiest):
+🚧 **UNDER CONSTRUCTION** 🚧  
+Publishing to PyPI would allow users to install with just `pip install cdippy  
+
+ 2) Install from source (for developing or local control of library):  
+ **Pre-requisite:** [`git`](https://git-scm.com/doc) must be installed  
+ The `cdippy`source code lives [here](https://github.com/cdipsw/CDIPpy).  
+ * Clone the repository: `git clone 
+
+ 3) Install from GitHub (easiest when package is not published)  
+ **Pre-requisite:** [`pip`](https://pip.pypa.io/en/stable/) must be installed  
+
+---
+
+## Contained in this library
+🚧 **UNDER CONSTRUCTION** 🚧
+
+*TODO* Work on a comprehensive list of tools/features/uses of this library
+
+---

docs/user_guide/plotting.md

@@ -0,0 +1,3 @@
+# 🚧 **UNDER CONSTRUCTION** 🚧
+
+This page is still being written.

mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: CDIPpy Docs
+theme:
+  name: readthedocs
+
+nav:
+  - Home: index.md
+  - Quick start: quickstart.md
+  - Users guide:
+    - Installation: user_guide/index.md
+    - Data access: user_guide/data_access.md
+    - Data visualization: user_guide/plotting.md
+  - Developers guide:
+    - Installation: dev_guide/index.md
+    - Contributing: dev_guide/contribute.md
+  - Examples: examples/index.md

pyproject.toml

@@ -23,7 +23,8 @@ dev = [
     "black",
     "coverage",
     "flake8",
-    "pre-commit",
+    "mkdocs",
+    "pre-commit"
 ]
 
 [project.urls]