diff --git a/README.rst b/README.rst index f692014..a9d858e 100644 --- a/README.rst +++ b/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 `_, + `Dask `_, and `NumPy `_. + You will need to separately install `TensorFlow `_ + or `PyTorch `_ to use those data loaders or + Xarray accessors. `Review the installation instructions `_ + for more details. + +Documentation +------------ + +Documentation is hosted on ReadTheDocs: https://xbatcher.readthedocs.org + +License +------------ + +Apache License 2.0, see LICENSE file. diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index a9908ce..305fd3c 100644 --- a/ci/requirements/doc.yml +++ b/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 diff --git a/doc/api.rst b/doc/api.rst index 168fde4..6475e88 100644 --- a/doc/api.rst +++ b/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: diff --git a/doc/conf.py b/doc/conf.py index 7addfa4..4fc2d4a 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/contributing.rst b/doc/contributing.rst index 31ebd04..3bc4bfd 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -243,8 +243,10 @@ Continuous integration Continuous integration is done with `GitHub Actions `_. -There is currently 1 workflow configured: +There are currently 3 workflows configured: - `main.yaml `_ - Run test suite with pytest. - `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 `_ - Draft + release notes based on PR titles and labels. diff --git a/doc/index.rst b/doc/index.rst index 9f0b70b..db25016 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -87,7 +87,7 @@ or via a built-in `Xarray accessor