Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update theme and reference documentation #146

Merged
merged 10 commits into from
Jan 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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