Update theme and reference documentation (#146)

Author: maxrjones

README.rst

@@ -31,3 +31,36 @@ such as PyTorch_ or TensorFlow_. View the |docs| for more info.
 .. |license| image:: https://img.shields.io/github/license/xarray-contrib/xbatcher.svg
    :target: https://github.com/xarray-contrib/xbatcher
    :alt: license
+
+Installation
+------------
+
+Xbatcher can be installed from PyPI as::
+
+    python -m pip install xbatcher
+
+Or via Conda as::
+
+    conda install -c conda-forge xbatcher
+
+Or from source as::
+
+    python -m pip install git+https://github.com/xarray-contrib/xbatcher.git
+
+.. note::
+   The required dependencies installed with Xbatcher are `Xarray <https://xarray.dev/>`_,
+   `Dask <https://www.dask.org/>`_, and `NumPy <https://numpy.org/>`_.
+   You will need to separately install `TensorFlow <https://www.tensorflow.org/>`_
+   or `PyTorch <https://pytorch.org/>`_ to use those data loaders or
+   Xarray accessors. `Review the installation instructions <https://xbatcher.readthedocs.io/en/latest/#optional-dependencies>`_
+   for more details.
+
+Documentation
+------------
+
+Documentation is hosted on ReadTheDocs: https://xbatcher.readthedocs.org
+
+License
+------------
+
+Apache License 2.0, see LICENSE file.

ci/requirements/doc.yml

@@ -1,17 +1,17 @@
-name: xbatcher-docs
+name: xbatcher-docs-pydata
 channels:
   - conda-forge
   - nodefaults
 dependencies:
   - python=3.8
   - dask
+  - pydata-sphinx-theme
   - ipython
   - matplotlib
   - numpy
   - numpydoc
-  - pangeo-sphinx-book-theme
   - pytest
-  - sphinx
+  - sphinx<6
   - sphinx-autosummary-accessors
   - sphinx-copybutton
   - xarray

doc/api.rst

@@ -5,8 +5,19 @@ API reference
 
 This page provides an auto-generated summary of Xbatcher's API.
 
-Dataset.batch and DataArray.batch
-=================================
+Core
+====
+
+.. currentmodule:: xbatcher
+
+.. autosummary::
+   :toctree: generated/
+
+   BatchGenerator
+   BatchSchema
+
+Xbatcher xarray accessors
+=========================
 
 .. currentmodule:: xarray
 
@@ -17,19 +28,15 @@ Dataset.batch and DataArray.batch
    Dataset.batch.generator
    DataArray.batch.generator
 
-Core
-====
-
-.. autoclass:: xbatcher.BatchGenerator
-   :members:
-
 Dataloaders
 ===========
-.. autoclass:: xbatcher.loaders.torch.MapDataset
-   :members:
 
-.. autoclass:: xbatcher.loaders.torch.IterableDataset
-   :members:
+.. currentmodule:: xbatcher
+
+.. autosummary::
+   :toctree: generated/
 
-.. autoclass:: xbatcher.loaders.keras.CustomTFDataset
+   loaders.torch.MapDataset
+   loaders.torch.IterableDataset
+   loaders.keras.CustomTFDataset
    :members:

doc/conf.py

@@ -14,6 +14,7 @@
 
 # type: ignore
 
+import datetime
 import sys
 
 import sphinx_autosummary_accessors
@@ -54,26 +55,13 @@
     "sphinx_copybutton",
 ]
 
-# only execute notebooks without any outputs
-# https://nbsphinx.readthedocs.io/en/0.2.14/never-execute.html
 nbsphinx_execute = "auto"
 
 
-# http://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
-def skip(app, what, name, obj, skip, options):
-    if name == "__init__":
-        return False
-    return skip
-
-
-def setup(app):
-    app.connect("autodoc-skip-member", skip)
-
-
 autodoc_mock_imports = ["torch", "tensorflow"]
 
 # link to github issues
-extlinks = {"issue": ("https://github.com/xarray-contrib/xbatcher/issues/%s", "GH")}
+extlinks = {"issue": ("https://github.com/xarray-contrib/xbatcher/issues/%s", "#%s")}
 
 # sphinx-copybutton configurations (from https://github.com/pydata/xarray/blob/main/doc/conf.py)
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
@@ -97,7 +85,7 @@ def setup(app):
 
 # General information about the project.
 project = "xbatcher"
-copyright = "2021, xbatcher developers"
+copyright = f"2016-{datetime.datetime.now().year}, xbatcher developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -152,15 +140,14 @@ def setup(app):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # tml_theme = 'default'
-html_theme = "pangeo_sphinx_book_theme"
+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 = {
-    "repository_url": "https://github.com/xarray-contrib/xbatcher",
-    "use_repository_button": True,
-    "use_issues_button": True,
+    "search_bar_position": "sidebar",
+    "github_url": "https://github.com/xarray-contrib/xbatcher",
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -175,7 +162,7 @@ def setup(app):
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-# html_logo = None
+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

doc/contributing.rst

@@ -243,8 +243,10 @@ Continuous integration
 
 Continuous integration is done with `GitHub Actions <https://docs.github.com/en/actions/learn-github-actions>`_.
 
-There is currently 1 workflow configured:
+There are currently 3 workflows configured:
 
 - `main.yaml <https://github.com/xarray-contrib/xbatcher/blob/main/.github/workflows/main.yaml>`_ - Run test suite with pytest.
 - `pypi-release.yaml <https://github.com/xarray-contrib/xbatcher/blob/main/.github/workflows/pypi-release.yaml>`_ - Publish
   wheels to TestPyPI and PyPI on a tagged release. The pull request trigger can be uncommented to test a release using Test PyPI.
+- `release-drafter.yml <https://github.com/xarray-contrib/xbatcher/blob/main/.github/workflows/release-drafter.yml>`_ - Draft
+  release notes based on PR titles and labels.

doc/index.rst

@@ -87,7 +87,7 @@ or via a built-in `Xarray accessor <http://xarray.pydata.org/en/stable/internals
    :maxdepth: 2
    :caption: Contents:
 
-   roadmap
    api
    demo
+   roadmap
    contributing