From 9cf0fff60b72dafedd8768032a4dd76865be7184 Mon Sep 17 00:00:00 2001 From: Timothy Smith Date: Thu, 14 Dec 2023 11:46:00 -0700 Subject: [PATCH] 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 | 29 +++++++++++++ .gitignore | 4 ++ README.md | 21 ++++++++++ docs/contributing.rst | 74 ++++++++++++++++++++++++++++++++++ docs/index.rst | 26 ++++++++++-- docs/installation.rst | 49 ++++++++++++++++++++++ docs/support.rst | 7 ++++ pyproject.toml | 2 + 8 files changed, 208 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/publish.yaml create mode 100644 docs/contributing.rst create mode 100644 docs/installation.rst create mode 100644 docs/support.rst diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 0000000..2361de6 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 68bc17f..2b6e290 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ +# Additions +.DS_Store + + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/README.md b/README.md index f0561d5..a9735f2 100644 --- a/README.md +++ b/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 . +``` diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..a0242d2 --- /dev/null +++ b/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 +`_ +describing how to make a pull request from a fork, and also +`this page 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 `_ +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 `_ +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 +`_ +as outlined `on this page +`_. diff --git a/docs/index.rst b/docs/index.rst index f276df9..def7ea1 100644 --- a/docs/index.rst +++ b/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) + Replay MOM6 (1 Degree) + Replay CICE6 (1 Degree) + +.. toctree:: + :maxdepth: 1 + :caption: Community + + contributing + support + +.. toctree:: + :maxdepth: 1 + :caption: References - example_replay_fv3 - example_replay_mom6 - example_replay_cice6 api diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..13165db --- /dev/null +++ b/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 `_ +and install it as follows:: + + git clone https://github.com/NOAA-PSL/ufs2arco.git + cd ufs2arco + pip install -e . + +Users are encourged to `fork `_ +the project and submit +`issues `_ +and +`pull requests `_. + +Running Example Notebooks or Building the Documentation Locally +=============================================================== + +Due to the way pandoc is installed via pip `as detailed here +`_ +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 +`_, +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. diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000..2e78216 --- /dev/null +++ b/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 `_, +with a sufficient description of the problem or question. diff --git a/pyproject.toml b/pyproject.toml index 2cb9399..98cd1df 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,8 @@ dependencies = [ "fsspec", "s3fs", "gcsfs", + "pytest", + "coverage", ] [project.optional-dependencies]