Skip to content

Commit

Permalink
Update theme and reference documentation (#146)
Browse files Browse the repository at this point in the history
  • Loading branch information
maxrjones authored Jan 7, 2023
1 parent 89746a7 commit 463227f
Show file tree
Hide file tree
Showing 6 changed files with 67 additions and 38 deletions.
33 changes: 33 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 3 additions & 3 deletions ci/requirements/doc.yml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
33 changes: 20 additions & 13 deletions doc/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
27 changes: 7 additions & 20 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@

# type: ignore

import datetime
import sys

import sphinx_autosummary_accessors
Expand Down Expand Up @@ -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}: "
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
4 changes: 3 additions & 1 deletion doc/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

0 comments on commit 463227f

Please sign in to comment.