Installation instructions and put package on Pypi (#7)

* setup for pip install

* better installation etc documentation

* add ds store to gitignore, rephrase doc a touch

.github/workflows/publish.yaml

@@ -0,0 +1,29 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ufs2arco
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,3 +1,7 @@
+# Additions
+.DS_Store
+
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -1,2 +1,23 @@
 # ufs2arco
 Tools for converting Unified Forecast System (UFS) output to Analysis Ready, Cloud Optimized (ARCO) format
+
+## Installation
+
+
+### Installation from pip
+
+```bash
+pip install ufs2arco
+```
+
+### Installation from GitHub
+
+To obtain the latest development version, clone
+[the repository](https://github.com/NOAA-PSL/ufs2arco>)
+and install it as follows
+
+```bash
+git clone https://github.com/NOAA-PSL/ufs2arco.git
+cd ufs2arco
+pip install -e .
+```

docs/contributing.rst

@@ -0,0 +1,74 @@
+How to Contribute
+#################
+
+If you're interested in contributing to ufs2arco, thank you! Here are some pointers
+for doing so.
+
+1. Environment Setup
+--------------------
+
+First you will want to fork the main repository, and clone that fork onto the
+machine where you'll do the development work.
+Ultimately, we want any contribution in the form of a pull request that is on
+this code fork *on a separate branch from the main branch*.
+If this is unfamiliar terminology, check out
+`this git tutorial
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
+describing how to make a pull request from a fork, and also
+`this page about branches
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches>`_.
+
+After forking the repository, create and activate a development environment as follows::
+
+    cd ufs2arco
+    conda env create -f environment.yaml
+    conda activate ufs2arco
+    pip install -e . --no-deps
+
+and you can test that everything went smoothly by running the unittest suite::
+
+    pytest
+
+2. Develop Contributions
+------------------------
+
+Add those awesome contributions to your development branch.
+If you are adding a feature to the code base, then make sure to periodically run the test 
+suite as shown above::
+
+    cd ufs2arco
+    conda activate ufs2arco
+    pytest
+
+Ideally, we'll want the new developments to have tests and
+`docstrings <https://peps.python.org/pep-0257/>`_
+of their own, so
+please consider writing tests and documentation during development.
+
+If you are adding to the documentation, then you'll want to first verify that
+the documentation builds locally in the environment you created::
+
+    cd ufs2arco/docs
+    conda activate ufs2arco
+    make html
+
+After that, you can open the generated html files to view in your web browser::
+
+    open _build/html/index.html
+
+Rinse and repeat as you add your documentation :)
+
+Don't hesitate to
+`create an issue <https://github.com/NOAA-PSL/ufs2arco/issues/new>`_
+describing the feature or documentation you're interested in adding, and any areas you might like
+some help.
+We'd be happy to discuss it and help where we can.
+
+3. Submit a Pull Request
+------------------------
+
+We recommend doing this on our repository's
+`PR webpage 
+<https://github.com/NOAA-PSL/ufs2arco/pulls>`_
+as outlined `on this page
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.

docs/index.rst

@@ -10,9 +10,27 @@ Tools for converting Unified Forecast System (UFS) output to Analysis Ready, Clo
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
+   :caption: Getting Started
+
+   installation
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples
+
+   Replay FV3 (1 Degree) <example_replay_fv3>
+   Replay MOM6 (1 Degree) <example_replay_mom6>
+   Replay CICE6 (1 Degree) <example_replay_cice6>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Community
+
+   contributing
+   support
+
+.. toctree::
+   :maxdepth: 1
+   :caption: References
 
-   example_replay_fv3
-   example_replay_mom6
-   example_replay_cice6
    api

docs/installation.rst

@@ -0,0 +1,49 @@
+Installation
+############
+
+Installation from pip
+=====================
+
+ufs2arco can be installed using pip::
+
+    pip install ufs2arco
+
+
+Installation from GitHub
+========================
+
+To obtain the latest development version, clone
+`the repository <https://github.com/NOAA-PSL/ufs2arco>`_
+and install it as follows::
+
+    git clone https://github.com/NOAA-PSL/ufs2arco.git
+    cd ufs2arco
+    pip install -e .
+
+Users are encourged to `fork <https://help.github.com/articles/fork-a-repo/>`_
+the project and submit 
+`issues <https://github.com/NOAA-PSL/ufs2arco/issues>`_
+and
+`pull requests <https://github.com/NOAA-PSL/ufs2arco/pulls>`_.
+
+Running Example Notebooks or Building the Documentation Locally
+===============================================================
+
+Due to the way pandoc is installed via pip `as detailed here
+<https://stackoverflow.com/a/71585691>`_
+it is recommended to create an environment with conda in order to build the
+documentation locally.
+This is also recommended for running any of the example notebooks locally, since
+there are a couple of additional dependencies required.
+To do this, first download `this environment.yaml file
+<https://github.com/NOAA-PSL/ufs2arco/blob/main/environment.yaml>`_,
+then create the conda environment::
+
+    conda env create -f environment.yaml
+    conda activate ufs2arco
+
+Note that you will then want to add ufs2arco to the jupyter kernel::
+
+    python -m ipykernel install --user --name=ufs2arco
+
+so that it can be accessed from jupyter lab / notebook.

docs/support.rst

@@ -0,0 +1,7 @@
+Getting Support
+###############
+
+If you think there is a bug in the code or have any questions about using ufs2arco,
+please 
+`submit an issue <https://github.com/NOAA-PSL/ufs2arco/issues/new>`_,
+with a sufficient description of the problem or question.

pyproject.toml

@@ -23,6 +23,8 @@ dependencies = [
     "fsspec",
     "s3fs",
     "gcsfs",
+    "pytest",
+    "coverage",
 ]
 
 [project.optional-dependencies]