Add contributing section to docs

.github/workflows/changelog.yml

@@ -23,4 +23,3 @@ jobs:
           echo "Please see https://landlab.readthedocs.io/en/master/development/contribution/index.html?highlight=towncrier#news-entries for guidance."
             false
           fi
-

.github/workflows/docs.yml

@@ -26,9 +26,9 @@ jobs:
         if:
           github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
           github.repository
-    
+
         runs-on: ubuntu-latest
-        
+
         defaults:
           run:
             shell: bash -l {0}
@@ -44,10 +44,10 @@ jobs:
 
           - name: Show conda installation info
             run: conda info
-    
+
           - name: Install dependencies
             run: |
               pip install nox
 
           - name: Build documentation
-            run: nox -s docs
+            run: nox -s build-docs

.github/workflows/flake8.yml → .github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: Flake8
+name: Lint
 
 on: [push, pull_request]
 

.github/workflows/prerelease.yml

@@ -28,19 +28,19 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: "3.9"
-      
+
       - name: Install twine
         run: |
           pip install --upgrade pip wheel setuptools
           pip install twine
           python --version
           pip --version
           twine --version
-        
+
       - name: Create source distribution
         run: |
           python setup.py sdist --dist-dir wheelhouse
-        
+
       - name: Upload source distribution
         run: |
           twine upload --skip-existing wheelhouse/*.tar.gz

.github/workflows/release.yml

@@ -28,19 +28,19 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: "3.9"
-      
+
       - name: Install twine
         run: |
           pip install --upgrade pip wheel setuptools
           pip install twine
           python --version
           pip --version
           twine --version
-        
+
       - name: Create source distribution
         run: |
           python setup.py sdist --dist-dir wheelhouse
-        
+
       - name: Upload source distribution
         run: |
           twine upload --skip-existing wheelhouse/*.tar.gz

.github/workflows/test.yml

@@ -43,4 +43,3 @@ jobs:
 
       - name: Test package
         run: nox -s tests
-

.pre-commit-config.yaml

@@ -21,11 +21,13 @@ repos:
     require_serial: true
     types_or: [python, pyi, jupyter]
     additional_dependencies: [".[jupyter]"]
+
 - repo: https://gitlab.com/pycqa/flake8
-  rev: 3.9.2
+  rev: 5.0.4
   hooks:
   - id: flake8
     # additional_dependencies: [flake8-bugbear]
+
 - repo: https://gitlab.com/iamlikeme/nbhooks
   rev: 1.0.0
   hooks:
@@ -36,8 +38,37 @@ repos:
     files: \.ipynb$
     language: python
     language_version: python3
+
 - repo: https://github.com/asottile/pyupgrade
   rev: v2.34.0
   hooks:
   -   id: pyupgrade
       args: [--py38-plus]
+
+- repo: https://github.com/PyCQA/isort
+  rev: 5.10.1
+  hooks:
+    - id: isort
+      files: \.py$
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.3.0
+  hooks:
+    - id: check-builtin-literals
+    - id: check-added-large-files
+    - id: check-case-conflict
+    - id: check-toml
+    - id: check-yaml
+    - id: debug-statements
+    - id: end-of-file-fixer
+    - id: forbid-new-submodules
+    - id: trailing-whitespace
+
+- repo: https://github.com/PyCQA/pydocstyle
+  rev: 6.1.1
+  hooks:
+    - id: pydocstyle
+      files: src/bmi_wavewatch3/.*\.py$
+      args:
+        # - --convention=numpy
+        - --select=D417

.readthedocs.yaml

@@ -1,8 +1,8 @@
 version: 2
 
 sphinx:
-  builder: html
-  configuration: docs/source/conf.py
+  builder: dirhtml
+  configuration: docs/conf.py
   fail_on_warning: false
 
 formats:

AUTHORS.rst

@@ -1,3 +1,4 @@
+=======
 Credits
 =======
 

LICENSE.rst

@@ -23,4 +23,3 @@ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
-

README.rst

@@ -39,23 +39,43 @@ All data sources provide both global and regional grids.
 
 .. end-abstract
 
-Installation
-------------
+Quickstart
+----------
 
-.. start-installation
+.. start-quickstart
 
-*bmi_wavewatch3* can be installed by running ``pip install bmi-wavewatch3``. It requires Python >= 3.8 to run.
+To get started you will first need to install the *bmi-wavewatch3* package, which is currently distributed
+on `PyPI`_ and `conda-forge`_.
 
-If you simply can't wait for the latest release, you can install *bmi_wavewatch3*
-directly from GitHub,
+.. tab:: pip
+
+  .. code-block:: bash
+
+    pip install bmi-wavewatch3
+
+.. tab:: mamba
+
+  .. code-block:: bash
+
+    conda install mamba
+    mamba install bmi-wavewatch3 -c conda-forge
+
+.. tab:: conda
+
+  .. code-block:: bash
+
+    conda install bmi-wavewatch3 -c conda-forge
+
+You can now begin to download WAVEWATCH III data with the *ww3* command,
 
 .. code-block:: bash
 
-   $ pip install git+https://github.com/csdms/bmi-wavewatch3
+  ww3 fetch "2010-05-22"
 
-*bmi_wavewatch3* is also available through *conda*, ``conda install bmi-wavewatch3 -c conda-forge``.
+.. _PyPI: https://pypi.org/project/bmi-wavewatch3/
+.. _conda-forge: https://github.com/conda-forge/bmi-wavewatch3-feedstock
 
-.. end-installation
+.. end-quickstart
 
 Usage
 -----
@@ -67,19 +87,19 @@ To get started, you can download *WAVEWATCH III* data by date with the *ww3* com
 
 .. code-block:: bash
 
-    $ ww3 fetch "2010-05-22"
+    ww3 fetch "2010-05-22"
 
 You can also do this through Python,
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> from bmi_wavewatch3 import WaveWatch3
     >>> WaveWatch3.fetch("2010-05-22")
 
 The *bmi_wavewatch3* package provides the ``WaveWatch3`` class for downloading data and
 presenting it as an *xarray* *Dataset*.
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> from bmi_wavewatch3 import WaveWatch3
    >>> ww3 = WaveWatch3("2010-05-22")
@@ -89,7 +109,7 @@ presenting it as an *xarray* *Dataset*.
 
 Use the ``inc`` method to advance in time month-by-month,
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> ww3.date
    '2010-05-22'
@@ -121,7 +141,7 @@ separated from the date with a ``T`` (i.e. times can be given as ``YYYY-MM-DDTHH
 
 .. code:: bash
 
-  $ ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15"
+  ww3 plot --grid=at_4m --data-var=swh "2010-09-15T15"
 
 .. image:: https://raw.githubusercontent.com/csdms/bmi-wavewatch3/main/docs/source/_static/hurricane_julia-light.png
   :width: 100%
@@ -145,14 +165,14 @@ Plot data from Python
 
 This example is similar to the previous but uses the *bmi_wavewatch3* Python interface.
 
-.. code:: python
+.. code:: pycon
 
    >>> from bmi_wavewatch3 import WaveWatch3
    >>> ww3 = WaveWatch3("2009-11-08")
 
 The data can be accessed as an *xarray* *Dataset* through the ``data`` attribute.
 
-.. code:: python
+.. code:: pycon
 
    >>> ww3.data
    <xarray.Dataset>
@@ -182,7 +202,7 @@ The data can be accessed as an *xarray* *Dataset* through the ``data`` attribute
 The ``step`` attribute points to the current time slice into the data (i.e number of three hour increments
 since the start of the month),
 
-.. code:: python
+.. code:: pycon
 
    >>> ww3.step
    56
@@ -210,6 +230,3 @@ since the start of the month),
 .. _WAVEWATCH III thredds: https://www.ncei.noaa.gov/thredds-ocean/catalog/ncep/nww3/catalog.html
 .. _Singlegrid data: https://polar.ncep.noaa.gov/waves/hindcasts/nww3/
 .. _Multigrid data: https://polar.ncep.noaa.gov/waves/hindcasts/multi_1/
-
-
-