diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..c9f2a88 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,103 @@ +name: CI +on: + push: + branches: + - "main" + pull_request: + branches: + - "*" + schedule: + - cron: "0 0 * * *" # Daily “At 00:00” + workflow_dispatch: # allows you to trigger manually + +jobs: + build: + name: Build (${{ matrix.python-version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} + defaults: + run: + shell: bash -l {0} + strategy: + fail-fast: false + matrix: + os: ["ubuntu-latest"] + python-version: ["3.7", "3.8", "3.9"] + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 # Fetch all history for all branches and tags. + - name: Set environment variables + run: | + if [[ ${{ matrix.os }} == windows* ]] ; + then + echo "CONDA_ENV_FILE=ci/environment-windows.yml" >> $GITHUB_ENV + else + echo "CONDA_ENV_FILE=ci/environment.yml" >> $GITHUB_ENV + + fi + echo "PYTHON_VERSION=${{ matrix.python-version }}" >> $GITHUB_ENV + - name: Cache conda + uses: actions/cache@v2 + with: + path: ~/conda_pkgs_dir + key: + ${{ runner.os }}-conda-py${{ matrix.python-version }}-${{ + hashFiles('ci/requirements/**.yml') }} + - uses: conda-incubator/setup-miniconda@v2 + with: + channels: conda-forge + channel-priority: strict + mamba-version: "*" + activate-environment: sandbox-devel + auto-update-conda: false + python-version: ${{ matrix.python-version }} + use-only-tar-bz2: true + + - name: Install conda dependencies + run: | + mamba env update -f $CONDA_ENV_FILE + + - name: Set up conda environment + shell: bash -l {0} + run: | + python -m pip install -e . + conda list + + - name: Run Tests + shell: bash -l {0} + run: | + pytest --cov=./ --cov-report=xml + + - name: Upload code coverage to Codecov + uses: codecov/codecov-action@v1 + with: + file: ./coverage.xml + flags: unittests + env_vars: RUNNER_OS,PYTHON_VERSION + name: codecov-umbrella + fail_ci_if_error: false + + docs-build: + name: Documentation build + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + + - name: Install package + run: | + python -m pip install --upgrade pip + python -m pip install -e . + + - name: Install documentation dependencies + run: | + python -m pip install -r docs/requirements-docs.txt + + - name: Build docs + run: | + cd docs + make html diff --git a/.github/workflows/linting.yaml b/.github/workflows/linting.yaml new file mode 100644 index 0000000..85a38b6 --- /dev/null +++ b/.github/workflows/linting.yaml @@ -0,0 +1,16 @@ +name: code-style + +on: + push: + branches: 'main' + pull_request: + branches: '*' + +jobs: + linting: + name: "pre-commit hooks" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + - uses: pre-commit/action@v2.0.0 diff --git a/.github/workflows/pypi.yaml b/.github/workflows/pypi.yaml new file mode 100644 index 0000000..8cf2831 --- /dev/null +++ b/.github/workflows/pypi.yaml @@ -0,0 +1,26 @@ +name: Upload Package to PyPI + +on: + release: + types: [created] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install setuptools setuptools-scm wheel twine + - name: Build and publish + env: + TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} + TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} + run: | + python setup.py sdist bdist_wheel + twine upload dist/* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..e10eaa9 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,51 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v3.2.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-docstring-first + - id: check-json + - id: check-yaml + - id: double-quote-string-fixer + + - repo: https://github.com/ambv/black + rev: 20.8b1 + hooks: + - id: black + + - repo: https://github.com/keewis/blackdoc + rev: v0.1.1 + hooks: + - id: blackdoc + + - repo: https://gitlab.com/pycqa/flake8 + rev: 3.8.3 + hooks: + - id: flake8 + + - repo: https://github.com/asottile/seed-isort-config + rev: v2.2.0 + hooks: + - id: seed-isort-config + - repo: https://github.com/pre-commit/mirrors-isort + rev: v5.4.2 + hooks: + - id: isort + + - repo: https://github.com/prettier/prettier + rev: 2.1.1 + hooks: + - id: prettier + + - repo: https://github.com/deathbeds/prenotebook + rev: f5bdb72a400f1a56fe88109936c83aa12cc349fa + hooks: + - id: prenotebook + args: + [ + '--keep-output', + '--keep-metadata', + '--keep-execution-count', + '--keep-empty', + ] diff --git a/.prettierrc.toml b/.prettierrc.toml new file mode 100644 index 0000000..addd6d3 --- /dev/null +++ b/.prettierrc.toml @@ -0,0 +1,3 @@ +tabWidth = 2 +semi = false +singleQuote = true diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..a0e5577 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,151 @@ +============================================= +Contributing to cmweather +============================================= + +Contributions are highly welcomed and appreciated. Every little help counts, +so do not hesitate! + +The following sections cover some general guidelines +regarding development in cmweather for maintainers and contributors. +Nothing here is set in stone and can't be changed. +Feel free to suggest improvements or changes in the workflow. + + + +.. contents:: Contribution links + :depth: 2 + + + +.. _submitfeedback: + +Feature requests and feedback +----------------------------- + +Do you like cmweather? Share some love on Twitter or in your blog posts! + +We'd also like to hear about your propositions and suggestions. Feel free to +`submit them as issues `_ and: + +* Explain in detail how they should work. +* Keep the scope as narrow as possible. This will make it easier to implement. + + +.. _reportbugs: + +Report bugs +----------- + +Report bugs for cmweather in the `issue tracker `_. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting, + specifically the Python interpreter version, installed libraries, and cmweather + version. +* Detailed steps to reproduce the bug. + +If you can write a demonstration test that currently fails but should pass +(xfail), that is a very useful commit to make as well, even if you cannot +fix the bug itself. + + +.. _fixbugs: + +Fix bugs +-------- + +Look through the `GitHub issues for bugs `_. + +Talk to developers to find out how you can fix specific bugs. + + +Write documentation +------------------- + +cmweather could always use more documentation. What exactly is needed? + +* More complementary documentation. Have you perhaps found something unclear? +* Docstrings. There can never be too many of them. +* Blog posts, articles and such -- they're all very appreciated. + +You can also edit documentation files directly in the GitHub web interface, +without using a local copy. This can be convenient for small fixes. + +.. note:: + Build the documentation locally with the following command: + + .. code:: bash + + $ conda env update -f ci/environment.yml + $ cd docs + $ make html + + The built documentation should be available in the ``docs/_build/``. + + + .. _`pull requests`: +.. _pull-requests: + +Preparing Pull Requests +----------------------- + + +#. Fork the + `cmweather GitHub repository `__. It's + fine to use ``cmweather`` as your fork repository name because it will live + under your user. + +#. Clone your fork locally using `git `_ and create a branch:: + + $ git clone git@github.com:YOUR_GITHUB_USERNAME/cmweather.git + $ cd cmweather + # now, to fix a bug or add feature create your own branch off "master": + + $ git checkout -b your-bugfix-feature-branch-name master + + + +#. Install `pre-commit `_ and its hook on the cmweather repo:: + + $ pip install --user pre-commit + $ pre-commit install + + Afterwards ``pre-commit`` will run whenever you commit. + + https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks + to ensure code-style and code formatting is consistent. + +#. Install dependencies into a new conda environment:: + + $ conda env update -f ci/environment.yml + + +#. Run all the tests + + Now running tests is as simple as issuing this command:: + + $ conda activate sandbox-devel + $ pytest --junitxml=test-reports/junit.xml --cov=./ --verbose + + + This command will run tests via the "pytest" tool against the latest Python version. + +#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 for naming. + + When committing, ``pre-commit`` will re-format the files if necessary. + +#. Commit and push once your tests pass and you are happy with your change(s):: + + $ git commit -a -m "" + $ git push -u + + +#. Finally, submit a pull request through the GitHub website using this data:: + + head-fork: YOUR_GITHUB_USERNAME/cmweather + compare: your-branch-name + + base-fork: openradar/cmweather + base: master diff --git a/LICENSE b/LICENSE index 882a4c0..07e484e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 openradar +Copyright (c) 2023 Open Radar Community Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..e9d35cf --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,6 @@ +include LICENSE +include README.rst + +recursive-include cmweather *.py +recursive-exclude * __pycache__ +recursive-exclude * *.py[co] diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..bc8a861 --- /dev/null +++ b/README.rst @@ -0,0 +1,56 @@ +.. image:: https://img.shields.io/github/workflow/status/openradar/cmweather/CI?logo=github&style=for-the-badge + :target: https://github.com/openradar/cmweather/actions + :alt: GitHub Workflow CI Status + +.. image:: https://img.shields.io/github/workflow/status/openradar/cmweather/code-style?label=Code%20Style&style=for-the-badge + :target: https://github.com/openradar/cmweather/actions + :alt: GitHub Workflow Code Style Status + +.. image:: https://img.shields.io/codecov/c/github/openradar/cmweather.svg?style=for-the-badge + :target: https://codecov.io/gh/openradar/cmweather + +.. If you want the following badges to be visible, please remove this line, and unindent the lines below + .. image:: https://img.shields.io/readthedocs/cmweather/latest.svg?style=for-the-badge + :target: https://cmweather.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + + .. image:: https://img.shields.io/pypi/v/cmweather.svg?style=for-the-badge + :target: https://pypi.org/project/cmweather + :alt: Python Package Index + + .. image:: https://img.shields.io/conda/vn/conda-forge/cmweather.svg?style=for-the-badge + :target: https://anaconda.org/conda-forge/cmweather + :alt: Conda Version + + +cmweather +========= + +Development +------------ + +For a development install, do the following in the repository directory: + +.. code-block:: bash + + conda env update -f ci/environment.yml + conda activate sandbox-devel + python -m pip install -e . + +Also, please install `pre-commit` hooks from the root directory of the created project by running:: + + pre-commit install + +These code style pre-commit hooks (black, isort, flake8, ...) will run every time you are about to commit code. + +.. If you want the following badges to be visible, please remove this line, and unindent the lines below + Re-create notebooks with Pangeo Binder + -------------------------------------- + + Try notebooks hosted in this repo on Pangeo Binder. Note that the session is ephemeral. + Your home directory will not persist, so remember to download your notebooks if you + made changes that you need to use at a later time! + + .. image:: https://img.shields.io/static/v1.svg?logo=Jupyter&label=Pangeo+Binder&message=GCE+us-central1&color=blue&style=for-the-badge + :target: https://binder.pangeo.io/v2/gh/openradar/cmweather/master?urlpath=lab + :alt: Binder diff --git a/binder/Dockerfile b/binder/Dockerfile new file mode 100644 index 0000000..a0e0508 --- /dev/null +++ b/binder/Dockerfile @@ -0,0 +1 @@ +FROM pangeo/base-image:2020.05.10 diff --git a/binder/apt.txt b/binder/apt.txt new file mode 100644 index 0000000..9ed1fed --- /dev/null +++ b/binder/apt.txt @@ -0,0 +1,2 @@ +vim +git diff --git a/binder/environment.yml b/binder/environment.yml new file mode 100644 index 0000000..62b38f8 --- /dev/null +++ b/binder/environment.yml @@ -0,0 +1,7 @@ +name: myenv +channels: + - conda-forge +dependencies: + - pangeo-notebook==2020.05.10 + - xarray + - hvplot diff --git a/binder/postBuild b/binder/postBuild new file mode 100755 index 0000000..f7e214e --- /dev/null +++ b/binder/postBuild @@ -0,0 +1,8 @@ +#!/bin/bash + +jupyter labextension install --clean \ + @jupyter-widgets/jupyterlab-manager \ + dask-labextension \ + @pyviz/jupyterlab_pyviz + +#EOF diff --git a/binder/start b/binder/start new file mode 100755 index 0000000..c082ce6 --- /dev/null +++ b/binder/start @@ -0,0 +1,9 @@ +#!/bin/bash -l + +# ==== ONLY EDIT WITHIN THIS BLOCK ===== + +export PANGEO_ENV="BINDER_TEMPLATE" + +# ==== ONLY EDIT WITHIN THIS BLOCK ===== + +exec "$@" diff --git a/ci/environment.yml b/ci/environment.yml new file mode 100644 index 0000000..ec70849 --- /dev/null +++ b/ci/environment.yml @@ -0,0 +1,13 @@ +name: sandbox-devel +channels: + - conda-forge +dependencies: + - codecov + - netcdf4 + - pip + - pytest + - pytest-cov + - xarray + - numpydoc + - nbsphinx + - pre-commit diff --git a/cmweather/__init__.py b/cmweather/__init__.py new file mode 100644 index 0000000..def1761 --- /dev/null +++ b/cmweather/__init__.py @@ -0,0 +1,10 @@ +#!/usr/bin/env python +# flake8: noqa +"""Top-level module for cmweather .""" +from pkg_resources import DistributionNotFound, get_distribution + +try: + __version__ = get_distribution(__name__).version +except DistributionNotFound: + # package is not installed + _version__ = '0.0.0' diff --git a/cmweather/core.py b/cmweather/core.py new file mode 100644 index 0000000..8217019 --- /dev/null +++ b/cmweather/core.py @@ -0,0 +1,25 @@ +import xarray as xr + +def my_mean_func(data): + """ + Computes mean of an xarray object. + + Parameters + ---------- + data : xarray.DataArray, xarray.Dataset + Input data + + Returns + ------- + mean : xarray.DataArray, xarray.Dataset + + Raises + ------ + TypeError + if input data is not an xarray DataArray or xarray Dataset. + """ + + if isinstance(data, (xr.Dataset, xr.DataArray)): + return data.mean() + + raise TypeError('input data must be xarray DataArray or xarray Dataset!') diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 0000000..aa1da5f --- /dev/null +++ b/codecov.yml @@ -0,0 +1,20 @@ +codecov: + require_ci_to_pass: no + max_report_age: off + +comment: false + +ignore: + - 'tests/*.py' + - 'setup.py' + +coverage: + precision: 2 + round: down + status: + project: + default: + target: 95 + informational: true + patch: off + changes: off diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..9b5b604 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/complexity.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/complexity.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/complexity" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/complexity" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2df9a8c --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\complexity.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\complexity.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..49da3d9 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,6 @@ +numpydoc +pydata-sphinx-theme +nbsphinx +ipython +ipykernel +- r ../requirements.txt diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..21c186f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,286 @@ +# -*- coding: utf-8 -*- +# +# complexity documentation build configuration file, created by +# sphinx-quickstart on Tue Jul 9 22:26:36 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os +import datetime + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +cwd = os.getcwd() +parent = os.path.dirname(cwd) +sys.path.insert(0, parent) + +import cmweather + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.extlinks', + 'numpydoc', + 'IPython.sphinxext.ipython_console_highlighting', + 'IPython.sphinxext.ipython_directive', + 'nbsphinx', +] + +extlinks = { + 'issue': ('https://github.com/openradar/cmweather/issues/%s', 'GH#'), + 'pr': ('https://github.com/openradar/cmweather/pull/%s', 'GH#')} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# Enable notebook execution +# https://nbsphinx.readthedocs.io/en/0.4.2/never-execute.html +# nbsphinx_execute = 'auto' +# Allow errors in all notebooks by +nbsphinx_allow_errors = True + +# Disable cell timeout +nbsphinx_timeout = -1 + + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'cmweather' +current_year = datetime.datetime.now().year +copyright = f'2020-{current_year}, Open Radar Community' +author = u'Open Radar Community' +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = cmweather.__version__.split('+')[0] +# The full version, including alpha/beta/rc tags. +release = cmweather.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'pydata_sphinx_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'cmweatherdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +# 'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +# 'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +# 'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'cmweather.tex', u'cmweather Documentation', + u'Open Radar Community', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'cmweather', u'cmweather Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'cmweather', u'cmweather Documentation', + author, 'cmweather', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'xarray': ('http://xarray.pydata.org/en/stable/', None), +} diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000..cd215d2 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,2 @@ + +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..f265490 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,18 @@ +.. include:: ../../README.rst + +Contents: +========= + +.. toctree:: + :maxdepth: 2 + + usage + contributing + + +Feedback +======== + + +If you encounter any errors or problems with **cmweather**, +please open an issue at the GitHub http://github.com/openradar/cmweather main repository. diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..6d68f9f --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,7 @@ +======== +Usage +======== + +To use cmweather in a project:: + + import cmweather diff --git a/notebooks/example-notebook.ipynb b/notebooks/example-notebook.ipynb new file mode 100644 index 0000000..cc5c2b1 --- /dev/null +++ b/notebooks/example-notebook.ipynb @@ -0,0 +1,73 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%load_ext autoreload\n", + "%autoreload 2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import xarray as xr\n", + "import cmweather\n", + "from cmweather.core import my_mean_func" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "ds = xr.tutorial.open_dataset('rasm')\n", + "ds" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "ds_x = my_mean_func(ds)\n", + "ds_x" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.6" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": {}, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..477f5c6 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,4 @@ +[tool.black] +line-length = 100 +target-version = ['py38'] +skip-string-normalization = true diff --git a/readthedocs.yml b/readthedocs.yml new file mode 100644 index 0000000..9abab7c --- /dev/null +++ b/readthedocs.yml @@ -0,0 +1,6 @@ +python: + version: 3 + setup_py_install: true + system_packages: true + install: + - requirements: docs/requirements-docs.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..7cfd846 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +netcdf4 +xarray diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..314dd42 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,18 @@ +[flake8] +exclude = docs +ignore = E203,E266,E501,W503,F401,E722,E402,C901 +max-line-length = 100 +max-complexity = 18 +select = B,C,E,F,W,T4,B9 + +[isort] +known_first_party=cmweather +known_third_party=pkg_resources,setuptools +multi_line_output=3 +include_trailing_comma=True +force_grid_wrap=0 +combine_as_imports=True +line_length=100 +skip= + docs/source/conf.py + setup.py diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..0834227 --- /dev/null +++ b/setup.py @@ -0,0 +1,44 @@ +#!/usr/bin/env python + +"""The setup script.""" + +from setuptools import find_packages, setup + +with open('requirements.txt') as f: + requirements = f.read().strip().split('\n') + +with open('README.rst') as f: + long_description = f.read() + +setup( + maintainer="Open Radar Community", + maintainer_email='mgrover@anl.gov', + python_requires='>=3.6', + classifiers=[ + 'Development Status :: 2 - Pre-Alpha', + 'License :: OSI Approved :: MIT License', + 'Natural Language :: English', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Topic :: Scientific/Engineering', + 'Operating System :: OS Independent', + 'Intended Audience :: Science/Research', + ], + description='A library of useful colormaps when visualizing weather and climate data, with numerous color vision deficiency friendly options', + install_requires=requirements, + license='MIT license', + long_description=long_description, + include_package_data=True, + keywords='cmweather', + name='cmweather', + packages=find_packages(include=['cmweather', 'cmweather.*']), + url='https://github.com/openradar/cmweather', + project_urls={ + 'Documentation': 'https://github.com/openradar/cmweather', + 'Source': 'https://github.com/openradar/cmweather', + 'Tracker': 'https://github.com/openradar/cmweather/issues' + }, + zip_safe=False, +) diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_core.py b/tests/test_core.py new file mode 100644 index 0000000..c46a3cd --- /dev/null +++ b/tests/test_core.py @@ -0,0 +1,12 @@ +import pytest +import xarray as xr + +def test_foo(): + assert 'foo' == 'foo' + +@pytest.mark.parametrize('dataset_name', ['rasm', 'air_temperature']) +def test_mean_func(dataset_name): + from cmweather.core import my_mean_func + ds = xr.tutorial.open_dataset(dataset_name) + results = my_mean_func(ds) + assert isinstance(results, xr.Dataset)