Skip to content

Commit 4fb8066

Browse files
shoyershoyer
committed
Initial sphinx docs.
For now, this includes API docs and the start of a tutorial.
1 parent 66cb22b commit 4fb8066

15 files changed

+920
-2
lines changed

Diff for: ‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
*.egg-info
22
build
33
dist
4+
docs/.ipynb_checkpoints
45
docs/_build
56
docs/_autosummary
67
__pycache__

Diff for: ‎.read-the-docs.yaml

+25
Original file line numberDiff line numberDiff line change
@@ -1 +1,26 @@
1+
<<<<<<< HEAD
12
# TODO
3+
=======
4+
# .readthedocs.yaml
5+
# Read the Docs configuration file
6+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
7+
8+
# Required
9+
version: 2
10+
11+
build:
12+
image: latest
13+
14+
# Build documentation in the docs/ directory with Sphinx
15+
sphinx:
16+
configuration: docs/conf.py
17+
18+
# Optionally set the version of Python and requirements required to build your docs
19+
python:
20+
version: "3.8"
21+
install:
22+
- requirements: docs/requirements.txt
23+
- method: pip
24+
path: .
25+
system_packages: false
26+
>>>>>>> f2470a9 (Initial sphinx docs.)

Diff for: ‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Diff for: ‎docs/api.md

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# API docs
2+
3+
```{eval-rst}
4+
.. currentmodule:: xarray_beam
5+
```
6+
7+
## Core data model
8+
9+
```{eval-rst}
10+
.. autosummary::
11+
:toctree: _autosummary
12+
13+
Key
14+
```
15+
16+
## Reading and writing data
17+
18+
```{eval-rst}
19+
.. autosummary::
20+
:toctree: _autosummary
21+
22+
DatasetToChunks
23+
ChunksToZarr
24+
DatasetToZarr
25+
```
26+
27+
## Aggregation
28+
29+
```{eval-rst}
30+
.. autosummary::
31+
:toctree: _autosummary
32+
33+
Mean.Globally
34+
Mean.PerKey
35+
MeanCombineFn
36+
```
37+
38+
## Rechunking
39+
40+
```{eval-rst}
41+
.. autosummary::
42+
:toctree: _autosummary
43+
44+
ConsolidateChunks
45+
ConsolidateVariables
46+
SplitChunks
47+
SplitVariables
48+
Rechunk
49+
```
50+
51+
## Utility functions
52+
53+
```{eval-rst}
54+
.. autosummary::
55+
:toctree: _autosummary
56+
57+
offsets_to_slices
58+
consolidate_chunks
59+
consolidate_variables
60+
consolidate_fully
61+
split_chunks
62+
split_variables
63+
in_memory_rechunk
64+
```

Diff for: ‎docs/conf.py

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
# Print Python environment info for easier debugging on ReadTheDocs
18+
19+
import sys
20+
import subprocess
21+
import xarray_beam # verify this works
22+
23+
print("python exec:", sys.executable)
24+
print("sys.path:", sys.path)
25+
print("pip environment:")
26+
subprocess.run([sys.executable, "-m", "pip", "list"])
27+
28+
print(f"xarray_beam: {xarray_beam.__version__}, {xarray_beam.__file__}")
29+
30+
# -- Project information -----------------------------------------------------
31+
32+
project = 'Xarray-Beam'
33+
copyright = '2021, Google LCC'
34+
author = 'The Xarray-Beam authors'
35+
36+
37+
# -- General configuration ---------------------------------------------------
38+
39+
# Add any Sphinx extension module names here, as strings. They can be
40+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
41+
# ones.
42+
extensions = [
43+
'sphinx.ext.autodoc',
44+
'sphinx.ext.autosummary',
45+
'sphinx.ext.napoleon',
46+
'myst_nb',
47+
]
48+
49+
# Add any paths that contain templates here, relative to this directory.
50+
templates_path = ['_templates']
51+
52+
# List of patterns, relative to source directory, that match files and
53+
# directories to ignore when looking for source files.
54+
# This pattern also affects html_static_path and html_extra_path.
55+
exclude_patterns = ['_build', '_templates', 'Thumbs.db', '.DS_Store']
56+
57+
intersphinx_mapping = {
58+
"xarray": ("https://xarray.pydata.org/en/latest/", None),
59+
}
60+
61+
# -- Options for HTML output -------------------------------------------------
62+
63+
# The theme to use for HTML and HTML Help pages. See the documentation for
64+
# a list of builtin themes.
65+
#
66+
html_theme = 'sphinx_rtd_theme'
67+
68+
# Add any paths that contain custom static files (such as style sheets) here,
69+
# relative to this directory. They are copied after the builtin static files,
70+
# so a file named "default.css" will overwrite the builtin "default.css".
71+
html_static_path = ['_static']
72+
73+
# -- Extension config
74+
75+
autosummary_generate = True
76+
77+
# https://myst-nb.readthedocs.io/en/latest/use/execute.html
78+
jupyter_execute_notebooks = "cache"
79+
# https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#removing-stdout-and-stderr
80+
nb_output_stderr = "remove-warn"
81+
82+
# https://stackoverflow.com/a/66295922/809705
83+
autodoc_typehints = "description"

Diff for: ‎docs/index.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
Coming soon.
1+
# Xarray-Beam
2+
3+
Welcome to the xarray-beam docs.
4+
5+
```{toctree}
6+
:maxdepth: 2
7+
tutorial.md
8+
api.md
9+
```

Diff for: ‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

Diff for: ‎docs/requirements.txt

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# doc requirements
2+
myst-nb==0.12.3
3+
myst-parser==0.13.7
4+
sphinx_rtd_theme
5+
6+
# xarray-beam requirements
7+
apache-beam==2.31.0
8+
dask==2021.7.2
9+
immutabledict==2.1.0
10+
numpy==1.20
11+
pandas==1.3.1
12+
rechunker==0.4.2
13+
xarray==0.19.0
14+
zarr==2.8.3

0 commit comments

Comments
 (0)