From 785ea1062fa6005cfc73ae1188e44dc3f48c729a Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 16:20:08 -0500 Subject: [PATCH 01/10] Update theme --- ci/requirements/doc.yml | 2 +- doc/conf.py | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index a9908ce..fef9729 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -5,11 +5,11 @@ channels: dependencies: - python=3.8 - dask + - furo - ipython - matplotlib - numpy - numpydoc - - pangeo-sphinx-book-theme - pytest - sphinx - sphinx-autosummary-accessors diff --git a/doc/conf.py b/doc/conf.py index 7addfa4..57dc849 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -54,8 +54,6 @@ "sphinx_copybutton", ] -# only execute notebooks without any outputs -# https://nbsphinx.readthedocs.io/en/0.2.14/never-execute.html nbsphinx_execute = "auto" @@ -152,7 +150,7 @@ 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 = "furo" # 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 From 86975dee91397e377fd86a3dfee8e28c3550b0a0 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 16:20:30 -0500 Subject: [PATCH 02/10] Add BatchSchema to API docs --- doc/api.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/api.rst b/doc/api.rst index 168fde4..b3b35d1 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -23,6 +23,9 @@ Core .. autoclass:: xbatcher.BatchGenerator :members: +.. autoclass:: xbatcher.BatchSchema + :members: + Dataloaders =========== .. autoclass:: xbatcher.loaders.torch.MapDataset From dcd27119699028b0213d5092e9976fdb773582d3 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 16:20:57 -0500 Subject: [PATCH 03/10] Document release drafter workflow --- doc/contributing.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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. From 1d6fdef079c3626e144b53aa74ebcba266aafa00 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 16:37:26 -0500 Subject: [PATCH 04/10] Fix sphinx warnings --- doc/conf.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 57dc849..b4123ec 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -71,7 +71,7 @@ def setup(app): 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}: " @@ -155,11 +155,7 @@ def setup(app): # 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, -} +html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 585a701dad35698a458a23f7ba82cbde6d7dacbd Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 17:32:53 -0500 Subject: [PATCH 05/10] Include classes in table of contents --- doc/api.rst | 20 +++++++++++--------- doc/conf.py | 14 ++------------ doc/index.rst | 2 +- 3 files changed, 14 insertions(+), 22 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index b3b35d1..2826bbd 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -20,19 +20,21 @@ Dataset.batch and DataArray.batch Core ==== -.. autoclass:: xbatcher.BatchGenerator - :members: +.. currentmodule:: xbatcher -.. autoclass:: xbatcher.BatchSchema - :members: +.. autosummary:: + :toctree: generated/ + + BatchGenerator + BatchSchema Dataloaders =========== -.. autoclass:: xbatcher.loaders.torch.MapDataset - :members: -.. autoclass:: xbatcher.loaders.torch.IterableDataset - :members: +.. 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 b4123ec..bfcc09f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,6 +14,7 @@ # type: ignore +import datetime import sys import sphinx_autosummary_accessors @@ -57,17 +58,6 @@ 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 @@ -95,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 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 Date: Thu, 5 Jan 2023 18:15:06 -0500 Subject: [PATCH 06/10] Update theme --- ci/requirements/doc.yml | 6 +++--- doc/api.rst | 24 +++++++++++++----------- doc/conf.py | 9 ++++++--- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index fef9729..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 - - furo + - pydata-sphinx-theme - ipython - matplotlib - numpy - numpydoc - pytest - - sphinx + - sphinx<6 - sphinx-autosummary-accessors - sphinx-copybutton - xarray diff --git a/doc/api.rst b/doc/api.rst index 2826bbd..6475e88 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -5,32 +5,34 @@ API reference This page provides an auto-generated summary of Xbatcher's API. -Dataset.batch and DataArray.batch -================================= +Core +==== -.. currentmodule:: xarray +.. currentmodule:: xbatcher .. autosummary:: :toctree: generated/ - :template: autosummary/accessor_method.rst - Dataset.batch.generator - DataArray.batch.generator + BatchGenerator + BatchSchema -Core -==== +Xbatcher xarray accessors +========================= -.. currentmodule:: xbatcher +.. currentmodule:: xarray .. autosummary:: :toctree: generated/ + :template: autosummary/accessor_method.rst - BatchGenerator - BatchSchema + Dataset.batch.generator + DataArray.batch.generator Dataloaders =========== +.. currentmodule:: xbatcher + .. autosummary:: :toctree: generated/ diff --git a/doc/conf.py b/doc/conf.py index bfcc09f..4fc2d4a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -140,12 +140,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # tml_theme = 'default' -html_theme = "furo" +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 = {} +html_theme_options = { + "search_bar_position": "sidebar", + "github_url": "https://github.com/xarray-contrib/xbatcher", +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -159,7 +162,7 @@ # 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 From d5af2afd71862876721f5866c1f0c2a67c811271 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 18:22:00 -0500 Subject: [PATCH 07/10] Add more info to README --- README.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.rst b/README.rst index f692014..81ff639 100644 --- a/README.rst +++ b/README.rst @@ -31,3 +31,34 @@ 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 docs `_ + for more instructions. + +## Documentation + +Documentation is hosted on ReadTheDocs: https://xbatcher.readthedocs.org + +## License + +Apache License 2.0, see LICENSE file. From 2cc6f393c8e4b0e14d43f8b45da682482e6eddf3 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 18:24:31 -0500 Subject: [PATCH 08/10] RST formatting --- README.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 81ff639..d71ef2a 100644 --- a/README.rst +++ b/README.rst @@ -55,10 +55,12 @@ Or from source as:: Xarray accessors. `Review the docs `_ for more instructions. -## Documentation +Documentation +------------ Documentation is hosted on ReadTheDocs: https://xbatcher.readthedocs.org -## License +License +------------ Apache License 2.0, see LICENSE file. From 66ef67f2328d87e534c5c41a2073b4729b7c05f7 Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 18:28:33 -0500 Subject: [PATCH 09/10] Fix formatting --- README.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index d71ef2a..1d511b9 100644 --- a/README.rst +++ b/README.rst @@ -48,12 +48,12 @@ 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 docs `_ - for more instructions. + 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 docs `_ + for more instructions. Documentation ------------ From f96af355c74085798f6027431680a38369d7e7cb Mon Sep 17 00:00:00 2001 From: Max Jones <14077947+maxrjones@users.noreply.github.com> Date: Thu, 5 Jan 2023 18:30:07 -0500 Subject: [PATCH 10/10] Update link --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 1d511b9..a9d858e 100644 --- a/README.rst +++ b/README.rst @@ -52,8 +52,8 @@ Or from source as:: `Dask `_, and `NumPy `_. You will need to separately install `TensorFlow `_ or `PyTorch `_ to use those data loaders or - Xarray accessors. `Review the docs `_ - for more instructions. + Xarray accessors. `Review the installation instructions `_ + for more details. Documentation ------------