Skip to content

Commit 8d02884

Browse files
dcheriandcherian
authored
Add combining docs & fix tests (#34)
1 parent d6242e1 commit 8d02884

File tree

12 files changed

+584
-37
lines changed

12 files changed

+584
-37
lines changed

‎README.md

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
11
# rasterix: Raster tricks for Xarray
22

3+
[![GitHub Workflow CI Status](https://img.shields.io/github/actions/workflow/status/dcherian/rasterix/test.yml?branch=main&logo=github&style=flat)](https://github.com/dcherian/rasterix/actions)
4+
[![Documentation Status](https://readthedocs.org/projects/rasterix/badge/?version=latest)](https://rasterix.readthedocs.io/en/latest/?badge=latest)
5+
[![PyPI](https://img.shields.io/pypi/v/rasterix.svg?style=flat)](https://pypi.org/project/rasterix/)
6+
[![Conda-forge](https://img.shields.io/conda/vn/conda-forge/rasterix.svg?style=flat)](https://anaconda.org/conda-forge/rasterix)
7+
38
<img src="rasterix.png" width="300">
49

510
This WIP project contains tools to make it easier to analyze raster data with Xarray.
611

712
The intent is to provide reusable building blocks for the many sub-ecosystems around: e.g. rioxarray, odc-geo, etc.
813

14+
## Contents
15+
916
It currently has two pieces.
1017

11-
## 1. RasterIndex
18+
### 1. RasterIndex
1219

1320
See `src/ rasterix/raster_index.py` and `notebooks/raster_index.ipynb` for a brief demo.
1421

15-
## 2. Dask-aware rasterization wrappers
22+
### 2. Dask-aware rasterization wrappers
1623

1724
See `src/rasterix/rasterize.py` for dask-aware wrappers around [`exactextract`](https://github.com/dcherian/rasterix/blob/ec3f51e60e25aa312e6f48c4b22f91bec70413ed/rasterize.py#L165), [`rasterio.features.rasterize`](https://github.com/dcherian/rasterix/blob/ec3f51e60e25aa312e6f48c4b22f91bec70413ed/rasterize.py#L307), and [`rasterio.features.geometry_mask`](https://github.com/dcherian/rasterix/blob/ec3f51e60e25aa312e6f48c4b22f91bec70413ed/rasterize.py#L472).
1825

1926
This code is likely to move elsewhere!
2027

21-
## Trying it out
28+
## Installing
2229

2330
### PyPI
2431

@@ -28,7 +35,7 @@ This code is likely to move elsewhere!
2835
pip install rasterix
2936
```
3037

31-
### Installing and testing from source
38+
## Developing
3239

3340
1. Clone the repo
3441
```

‎docs/Makefile

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXATUOBUILD = sphinx-autobuild
8+
PAPER =
9+
BUILDDIR = _build
10+
11+
# Internal variables.
12+
PAPEROPT_a4 = -D latex_paper_size=a4
13+
PAPEROPT_letter = -D latex_paper_size=letter
14+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
15+
# the i18n builder cannot share the environment and doctrees with the others
16+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
17+
18+
.PHONY: help
19+
help:
20+
@echo "Please use \`make <target>' where <target> is one of"
21+
@echo " html to make standalone HTML files"
22+
@echo " rtdhtml Build html using same settings used on ReadtheDocs"
23+
@echo " livehtml Make standalone HTML files and rebuild the documentation when a change is detected. Also includes a livereload enabled web server"
24+
@echo " dirhtml to make HTML files named index.html in directories"
25+
@echo " singlehtml to make a single large HTML file"
26+
@echo " pickle to make pickle files"
27+
@echo " json to make JSON files"
28+
@echo " htmlhelp to make HTML files and a HTML help project"
29+
@echo " qthelp to make HTML files and a qthelp project"
30+
@echo " applehelp to make an Apple Help Book"
31+
@echo " devhelp to make HTML files and a Devhelp project"
32+
@echo " epub to make an epub"
33+
@echo " epub3 to make an epub3"
34+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
35+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
36+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
37+
@echo " text to make text files"
38+
@echo " man to make manual pages"
39+
@echo " texinfo to make Texinfo files"
40+
@echo " info to make Texinfo files and run them through makeinfo"
41+
@echo " gettext to make PO message catalogs"
42+
@echo " changes to make an overview of all changed/added/deprecated items"
43+
@echo " xml to make Docutils-native XML files"
44+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
45+
@echo " linkcheck to check all external links for integrity"
46+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
47+
@echo " coverage to run coverage check of the documentation (if enabled)"
48+
@echo " dummy to check syntax errors of document sources"
49+
50+
.PHONY: clean
51+
clean:
52+
rm -rf $(BUILDDIR)/*
53+
rm -rf generated/*
54+
rm -rf auto_gallery/
55+
56+
.PHONY: html
57+
html:
58+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
59+
@echo
60+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
61+
62+
.PHONY: rtdhtml
63+
rtdhtml:
64+
$(SPHINXBUILD) -T -j auto -E -W --keep-going -b html -d $(BUILDDIR)/doctrees -D language=en . $(BUILDDIR)/html
65+
@echo
66+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
67+
68+
69+
.PHONY: livehtml
70+
livehtml:
71+
# @echo "$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html"
72+
$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
73+
74+
.PHONY: dirhtml
75+
dirhtml:
76+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
77+
@echo
78+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
79+
80+
.PHONY: singlehtml
81+
singlehtml:
82+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
83+
@echo
84+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
85+
86+
.PHONY: html-noplot
87+
html-noplot:
88+
$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
89+
@echo
90+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
91+
92+
.PHONY: pickle
93+
pickle:
94+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
95+
@echo
96+
@echo "Build finished; now you can process the pickle files."
97+
98+
.PHONY: json
99+
json:
100+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
101+
@echo
102+
@echo "Build finished; now you can process the JSON files."
103+
104+
.PHONY: htmlhelp
105+
htmlhelp:
106+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
107+
@echo
108+
@echo "Build finished; now you can run HTML Help Workshop with the" \
109+
".hhp project file in $(BUILDDIR)/htmlhelp."
110+
111+
.PHONY: qthelp
112+
qthelp:
113+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
114+
@echo
115+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
116+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
117+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/xarray.qhcp"
118+
@echo "To view the help file:"
119+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/xarray.qhc"
120+
121+
.PHONY: applehelp
122+
applehelp:
123+
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
124+
@echo
125+
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
126+
@echo "N.B. You won't be able to view it unless you put it in" \
127+
"~/Library/Documentation/Help or install it in your application" \
128+
"bundle."
129+
130+
.PHONY: devhelp
131+
devhelp:
132+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
133+
@echo
134+
@echo "Build finished."
135+
@echo "To view the help file:"
136+
@echo "# mkdir -p $$HOME/.local/share/devhelp/xarray"
137+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/xarray"
138+
@echo "# devhelp"
139+
140+
.PHONY: epub
141+
epub:
142+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
143+
@echo
144+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
145+
146+
.PHONY: epub3
147+
epub3:
148+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
149+
@echo
150+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
151+
152+
.PHONY: latex
153+
latex:
154+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
155+
@echo
156+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
157+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
158+
"(use \`make latexpdf' here to do that automatically)."
159+
160+
.PHONY: latexpdf
161+
latexpdf:
162+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
163+
@echo "Running LaTeX files through pdflatex..."
164+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
165+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
166+
167+
.PHONY: latexpdfja
168+
latexpdfja:
169+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
170+
@echo "Running LaTeX files through platex and dvipdfmx..."
171+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
172+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
173+
174+
.PHONY: text
175+
text:
176+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
177+
@echo
178+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
179+
180+
.PHONY: man
181+
man:
182+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
183+
@echo
184+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
185+
186+
.PHONY: texinfo
187+
texinfo:
188+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
189+
@echo
190+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
191+
@echo "Run \`make' in that directory to run these through makeinfo" \
192+
"(use \`make info' here to do that automatically)."
193+
194+
.PHONY: info
195+
info:
196+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
197+
@echo "Running Texinfo files through makeinfo..."
198+
make -C $(BUILDDIR)/texinfo info
199+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
200+
201+
.PHONY: gettext
202+
gettext:
203+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
204+
@echo
205+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
206+
207+
.PHONY: changes
208+
changes:
209+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
210+
@echo
211+
@echo "The overview file is in $(BUILDDIR)/changes."
212+
213+
.PHONY: linkcheck
214+
linkcheck:
215+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
216+
@echo
217+
@echo "Link check complete; look for any errors in the above output " \
218+
"or in $(BUILDDIR)/linkcheck/output.txt."
219+
220+
.PHONY: doctest
221+
doctest:
222+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
223+
@echo "Testing of doctests in the sources finished, look at the " \
224+
"results in $(BUILDDIR)/doctest/output.txt."
225+
226+
.PHONY: coverage
227+
coverage:
228+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
229+
@echo "Testing of coverage in the sources finished, look at the " \
230+
"results in $(BUILDDIR)/coverage/python.txt."
231+
232+
.PHONY: xml
233+
xml:
234+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
235+
@echo
236+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
237+
238+
.PHONY: pseudoxml
239+
pseudoxml:
240+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
241+
@echo
242+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
243+
244+
.PHONY: dummy
245+
dummy:
246+
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
247+
@echo
248+
@echo "Build finished. Dummy builder generates no files."

‎docs/api.rst

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. currentmodule:: rasterix
22

3-
API Reference
4-
-------------
3+
API
4+
---
55

66
Functions
77
~~~~~~~~~
@@ -10,3 +10,12 @@ Functions
1010
:toctree: generated/
1111

1212
assign_index
13+
14+
15+
RasterIndex
16+
~~~~~~~~~~~
17+
18+
.. autosummary::
19+
:toctree: generated/
20+
21+
RasterIndex

‎docs/conf.py

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
"myst_nb",
3939
"sphinx_codeautolink",
4040
"sphinx_remove_toctrees",
41+
"sphinxext.opengraph",
4142
]
4243

4344
codeautolink_concat_default = True
@@ -48,7 +49,11 @@
4849
}
4950

5051
templates_path = ["_templates"]
51-
source_suffix = [".rst"]
52+
source_suffix = {
53+
".rst": "restructuredtext",
54+
".md": "myst-nb",
55+
".ipynb": "myst-nb",
56+
}
5257
master_doc = "index"
5358
language = "en"
5459

@@ -57,13 +62,15 @@
5762
# General information about the project.
5863
project = "rasterix"
5964
current_year = datetime.datetime.now().year
60-
copyright = f"2021-{current_year}, rasterix contributors"
65+
copyright = f"2025-{current_year}, rasterix contributors"
6166
author = "Rasterix Contributors"
6267

6368
# Myst_nb options
6469
nb_execution_excludepatterns = []
6570
nb_execution_raise_on_error = True
6671
nb_execution_mode = "cache"
72+
nb_execution_show_tb = True
73+
nb_remove_cell_tags = ["remove-cell"]
6774

6875
# The version info for the project you're documenting, acts as replacement for
6976
# |version| and |release|, also used in various other places throughout the
@@ -80,10 +87,13 @@
8087
# The name of the Pygments (syntax highlighting) style to use.
8188
pygments_style = "igor"
8289

90+
ogp_site_url = "https://rasterix.readthedocs.io/"
91+
8392

8493
# -- Options for HTML output ---------------------------------------------------
8594

8695
html_theme = "furo"
96+
html_logo = "rasterix.png"
8797

8898
# Theme options are theme-specific and customize the look and feel of a theme
8999
# further. For a list of options available for each theme, see the
@@ -116,6 +126,7 @@
116126
"numpy": ("https://numpy.org/doc/stable", None),
117127
"xarray": ("https://docs.xarray.dev/en/stable/", None),
118128
"xproj": ("https://xproj.readthedocs.io/en/stable/", None),
129+
"pyproj": ("https://pyproj4.github.io/pyproj/stable/", None),
119130
}
120131

121132
autosummary_generate = True
@@ -182,3 +193,5 @@
182193
"pd.Index": "~pandas.Index",
183194
"pd.NaT": "~pandas.NaT",
184195
}
196+
197+
numpydoc_class_members_toctree = False

0 commit comments

Comments
 (0)