Merge pull request #17 from openradar/add-git-history

ADD: Add revised docs

CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# 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](https://github.com/openradar/cmweather) 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](https://github.com/openradar/cmweather).
+
+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](https://github.com/openradar/cmweather/labels/type:%20bug).
+
+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:
+>
+> ```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-1)=
+
+## Preparing Pull Requests
+
+1. Fork the
+   [cmweather GitHub repository](https://github.com/openradar/cmweather). It's
+   fine to use `cmweather` as your fork repository name because it will live
+   under your user.
+
+2. Clone your fork locally using [git](https://git-scm.com/) and create a branch:
+
+   ```
+   $ git clone [email protected]: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
+   ```
+
+3. Install [pre-commit](https://pre-commit.com) 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.
+
+4. Install dependencies into a new conda environment:
+
+   ```
+   $ conda env update -f ci/environment.yml
+   ```
+
+5. 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.
+
+6. 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.
+
+7. Commit and push once your tests pass and you are happy with your change(s):
+
+   ```
+   $ git commit -a -m "<commit message>"
+   $ git push -u
+   ```
+
+8. 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
+   ```

README.md

@@ -0,0 +1,78 @@
+# cmweather
+
+```{image} https://github.com/openradar/cmweather/actions/workflows/ci.yaml/badge.svg
+:alt: Continuous Integration Status
+:target: https://github.com/openradar/cmweather/actions/workflows/ci.yaml
+```
+
+```{image} https://github.com/openradar/cmweather/actions/workflows/linting.yaml/badge.svg
+:alt: Code Style Status
+:target: https://github.com/openradar/cmweather/actions/workflows/linting.yaml
+```
+
+```{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
+
+## Motivation
+
+The motivation for this package is to contain weather maps relevant to the weather and climate community. There are **many** colormaps that are unique to the weather/climate community that are not included in core libraries such as [matplotlib](https://matplotlib.org/). This is also meant to be a community collaboration, across multiple domain-specific packages (ex. MetPy, GeoCAT, Py-ART). It is lightweight, easy to install, and we encourage contributions from across the community!
+
+While not all of the colormaps are color vision deficiency (CVD) friendly, we do include CVD friendly colormaps, and encourage users to use these when possible.
+
+## Installation
+
+cmweather can be found on both PyPI and conda-forge, installable using
+
+```bash
+mamba install cmweather
+```
+
+or
+
+```bash
+pip install cmweather
+```
+
+### Development Installation
+
+For a development install, do the following in the repository directory:
+
+```bash
+conda env update -f ci/environment.yml
+conda activate cmweather-dev
+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

ci/environment-docs.yml

@@ -10,6 +10,9 @@ dependencies:
   - netcdf4
   - xarray
   - pooch
+  - myst-nb
+  - myst-parser
+  - sphinx-design
   - pip
   - pip:
       - sphinxext-opengraph

cmweather/__init__.py

@@ -7,7 +7,7 @@
 colormaps for plotting.
 
 Available colormaps, reversed versions (_r) are also provided, these
-colormaps are available within matplotlib with names 'COLORMAP':
+colormaps are available within matplotlib with names:
 
     * BlueBrown10
     * BlueBrown11
@@ -62,5 +62,6 @@
 # Get the version
 try:
     __version__ = get_distribution(__name__).version
+    print(__version__)
 except DistributionNotFound:  # pragma: no cover
     __version__ = '0.0.0'  # pragma: no cover

cmweather/cm.py

@@ -2,7 +2,7 @@
 Radar related colormaps.
 
 Available colormaps, reversed versions (_r) are also provided, these
-colormaps are available within matplotlib with names 'pyart_COLORMAP':
+colormaps are available within matplotlib:
 
     * BlueBrown10
     * BlueBrown11

cmweather/cm_colorblind.py

@@ -2,7 +2,7 @@
 Colorblind friendly radar colormaps
 
 Available colormaps, reversed versions are also provided, these
-colormaps are available within matplotlib with names pyart_COLORMAP':
+colormaps are available within matplotlib:
 
     * HomeyerRainbow
     * balance

docs/source/api.md

@@ -0,0 +1,19 @@
+# Reference
+
+## Color Vision Deficiency Friendly Colormaps (`cmweather.cm_colorblind`)
+
+```{eval-rst}
+.. automodule:: cmweather.cm_colorblind
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## More Weather Colormaps (`cmweather.cm`)
+
+```{eval-rst}
+.. automodule:: cmweather.cm
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```

docs/source/conf.py

@@ -17,7 +17,7 @@
 # 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('.'))
+sys.path.insert(0, os.path.abspath('../../../cmweather'))
 
 cwd = os.getcwd()
 parent = os.path.dirname(cwd)
@@ -40,11 +40,18 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
     'numpydoc',
+    'myst_nb',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'nbsphinx',
+    'sphinx_design',
 ]
 
+
+# MyST config
+myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image']
+myst_url_schemes = ['http', 'https', 'mailto']
+
 extlinks = {
     'issue': ('https://github.com/openradar/cmweather/issues/%s', 'GH#'),
     'pr': ('https://github.com/openradar/cmweather/pull/%s', 'GH#'),
@@ -54,7 +61,10 @@
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ['.md', '.rst']
+
+# Generate the API documentation when building
+autoclass_content = 'both'
 
 # Enable notebook execution
 # https://nbsphinx.readthedocs.io/en/0.4.2/never-execute.html
@@ -221,6 +231,11 @@
     ('index', 'cmweather.tex', 'cmweather Documentation', 'Open Radar Community', 'manual'),
 ]
 
+# Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
+autosummary_generate = True
+autosummary_imported_members = True
+autodoc_typehints = 'description'
+
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 # latex_logo = None

docs/source/contributing.md

@@ -0,0 +1,3 @@
+```{include} ../../CONTRIBUTING.md
+
+```

docs/source/index.rst → docs/source/index.md

@@ -1,18 +1,19 @@
-.. include:: ../../README.md
+```{include} ../../README.md
 
-Contents:
-=========
+```
 
-.. toctree::
-   :maxdepth: 2
-
-   usage
-   contributing
-
-
-Feedback
-========
+```{toctree}
+---
+maxdepth: 2
+caption: Getting Started
+hidden:
+---
+usage
+contributing
+api
+```
 
+## Feedback
 
 If you encounter any errors or problems with **cmweather**,
 please open an issue at the GitHub http://github.com/openradar/cmweather main repository.