Skip to content

Commit fabb397

Browse files
lossyroblossyrob
committed
Updated docs.
1 parent 6bbe449 commit fabb397

10 files changed

+580
-35
lines changed

‎.gitignore

+4-4
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ docs/_build/
1919

2020
.ipynb_checkpoints/
2121

22-
tutorials/pystac-example*
23-
tutorials/spacenet-stac/
24-
tutorials/spacenet-cog-stac/
25-
tutorials/data/
22+
docs/tutorials/pystac-example*
23+
docs/tutorials/spacenet-stac/
24+
docs/tutorials/spacenet-cog-stac/
25+
docs/tutorials/data/

‎README.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -91,12 +91,15 @@ Use 'make' without arguments to see a list of available commands.
9191

9292

9393

94-
## Running the tutorials
94+
## Runing the quickstart and tutorials
9595

96-
There are tutorials written as jupyter notebooks in the `tutorials` folder. To run them, run a jupyter notebook with the `tutorials` directory as the notebook directory:
96+
There is a quickstart and tutorials written as jupyter notebooks in the `docs/tutorials` folder.
97+
To run the notebooks, run a jupyter notebook with the `docs` directory as the notebook directory:
9798

9899
```
99-
> PYTHONPATH=`pwd`:$PYTHONPATH jupyter notebook --ip 0.0.0.0 --port 8888 --notebook-dir=tutorials
100+
> PYTHONPATH=`pwd`:$PYTHONPATH jupyter notebook --ip 0.0.0.0 --port 8888 --notebook-dir=docs
100101
```
101102

103+
You can then navigate to the notebooks and execute them.
104+
102105
Requires [Jupyter](https://jupyter.org/) be installed.

‎docs/api.rst

-1
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@ STAC_IO is the utility mechanism that PySTAC uses for reading and writing. Users
4141
.. autoclass:: pystac.STAC_IO
4242
:members:
4343
:undoc-members:
44-
:exclude-members: stac_object_from_dict, STAC_OBJECT_CLASSES
4544

4645
Errors
4746
------

‎docs/concepts.rst

+252-21
Large diffs are not rendered by default.

‎docs/conf.py

+6-4
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@
4545
'sphinx.ext.viewcode',
4646
'sphinx.ext.napoleon',
4747
'sphinx.ext.githubpages',
48-
'sphinxcontrib.fulltoc'
48+
'sphinxcontrib.fulltoc',
49+
'nbsphinx',
50+
'RunNotebook'
4951
]
5052

5153
# Add any paths that contain templates here, relative to this directory.
@@ -70,7 +72,7 @@
7072
# List of patterns, relative to source directory, that match files and
7173
# directories to ignore when looking for source files.
7274
# This pattern also affects html_static_path and html_extra_path.
73-
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
75+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
7476

7577
# The name of the Pygments (syntax highlighting) style to use.
7678
pygments_style = None
@@ -87,12 +89,12 @@
8789
# further. For a list of options available for each theme, see the
8890
# documentation.
8991
#
90-
# html_theme_options = {}
92+
html_theme_options = {}
9193

9294
# Add any paths that contain custom static files (such as style sheets) here,
9395
# relative to this directory. They are copied after the builtin static files,
9496
# so a file named "default.css" will overwrite the builtin "default.css".
95-
html_static_path = ['_static']
97+
#html_static_path = ['_static']
9698

9799
# Custom sidebar templates, must be a dictionary that maps document names
98100
# to template names.

‎docs/contributing.rst

+21
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,24 @@ or an entire folder using:
3030
python -m unittest discover -v -s tests/
3131
3232
More details on using ``unittest`` are `here <https://docs.python.org/3/library/unittest.html>`_.
33+
34+
Code quality checks
35+
^^^^^^^^^^^^^^^^^^^
36+
37+
PySTAC uses `flake8 <http://flake8.pycqa.org/en/latest/>`_ and `yapf <https://github.com/google/yapf>`_ for code formatting and style checks.
38+
39+
To run the flake8 style checks:
40+
41+
.. code-block:: bash
42+
43+
> flake8 pystac
44+
> flake8 tests
45+
46+
To format code:
47+
48+
.. code-block:: bash
49+
50+
> yapf -ipr pystac
51+
> yapf -ipr tests
52+
53+
You could also run the ``.travis/style_checks`` script to check flake8 and yapf.

‎docs/index.rst

+11-1
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,26 @@ PySTAC Features
2828
* Allows easy iteration over STAC objects. Stac objects are only read in when needed.
2929
* Allows users to easily write "absolute published", "relative published" and "self-contained" catalogs as `described in the best practices documentation <https://github.com/radiantearth/stac-spec/blob/v0.8.0/best-practices.md#use-of-links>`_.
3030

31+
Example
32+
=======
33+
34+
.. code-block:: python
35+
36+
TKTK
37+
3138
3239
Acknowledgements
3340
================
3441

3542
This library builds on the code and concepts of `sat-stac <https://github.com/sat-utils/sat-stac>`_.
3643

44+
Table of Contents
45+
=================
46+
3747
.. toctree::
38-
:hidden:
3948
:maxdepth: 2
4049

50+
quickstart
4151
concepts
4252
api
4353
tutorials

‎docs/quickstart.ipynb

+269
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Quickstart\n",
8+
"\n",
9+
"This notebook shows how to use PySTAC to read through the public Sentinel catalog, and grab information for a single band's file."
10+
]
11+
},
12+
{
13+
"cell_type": "markdown",
14+
"metadata": {},
15+
"source": [
16+
"First, we want to hook into PySTAC to allow for reading of HTTP STAC items, as described in [the STAC_IO Concepts docs](concepts.html#using-stac-io). \n",
17+
"\n",
18+
"__Note:__ this requires the [requests](https://requests.kennethreitz.org/en/master) library be installed."
19+
]
20+
},
21+
{
22+
"cell_type": "code",
23+
"execution_count": 1,
24+
"metadata": {},
25+
"outputs": [],
26+
"source": [
27+
"from urllib.parse import urlparse\n",
28+
"import requests\n",
29+
"from pystac import STAC_IO\n",
30+
"\n",
31+
"def requests_read_method(uri):\n",
32+
" parsed = urlparse(uri)\n",
33+
" if parsed.scheme.startswith('http'):\n",
34+
" return requests.get(uri).text\n",
35+
" else:\n",
36+
" return STAC_IO.default_read_text_method(uri)\n",
37+
"\n",
38+
"STAC_IO.read_text_method = requests_read_method"
39+
]
40+
},
41+
{
42+
"cell_type": "markdown",
43+
"metadata": {},
44+
"source": [
45+
"We can then read the STAC catalog located at the publicly available endpoint hosted by AWS:"
46+
]
47+
},
48+
{
49+
"cell_type": "code",
50+
"execution_count": 3,
51+
"metadata": {},
52+
"outputs": [],
53+
"source": [
54+
"from pystac import Catalog\n",
55+
"\n",
56+
"cat = Catalog.from_file('https://sentinel-stac.s3.amazonaws.com/catalog.json')"
57+
]
58+
},
59+
{
60+
"cell_type": "markdown",
61+
"metadata": {},
62+
"source": [
63+
"There are a lot of items in this catalog; crawling through it all would take a significant amount of time. Here, we lean on the fact that [link resolution is lazy](concepts.html#lazy-resolution-of-stac-objects) and get to a catalog that contains items:"
64+
]
65+
},
66+
{
67+
"cell_type": "code",
68+
"execution_count": 4,
69+
"metadata": {},
70+
"outputs": [
71+
{
72+
"name": "stdout",
73+
"output_type": "stream",
74+
"text": [
75+
"Crawling through <Catalog id=sentinel-stac>\n",
76+
"Crawling through <Collection id=sentinel-2-l1c>\n",
77+
"Crawling through <Catalog id=9>\n",
78+
"Crawling through <Catalog id=V>\n"
79+
]
80+
}
81+
],
82+
"source": [
83+
"while len(cat.get_item_links()) == 0:\n",
84+
" print('Crawling through {}'.format(cat))\n",
85+
" cat = next(cat.get_children())"
86+
]
87+
},
88+
{
89+
"cell_type": "markdown",
90+
"metadata": {},
91+
"source": [
92+
"We can print some information about the catalog, including how many children it has:"
93+
]
94+
},
95+
{
96+
"cell_type": "code",
97+
"execution_count": 8,
98+
"metadata": {},
99+
"outputs": [
100+
{
101+
"name": "stdout",
102+
"output_type": "stream",
103+
"text": [
104+
"XK catalog\n",
105+
"Contains 388 items.\n"
106+
]
107+
}
108+
],
109+
"source": [
110+
"print(cat.description)\n",
111+
"print('Contains {} items.'.format(len(cat.get_item_links())))"
112+
]
113+
},
114+
{
115+
"cell_type": "markdown",
116+
"metadata": {},
117+
"source": [
118+
"Let's grab the first item, check out it's cloud cover, and start exploring the assets."
119+
]
120+
},
121+
{
122+
"cell_type": "code",
123+
"execution_count": 9,
124+
"metadata": {},
125+
"outputs": [],
126+
"source": [
127+
"item = next(cat.get_items())"
128+
]
129+
},
130+
{
131+
"cell_type": "code",
132+
"execution_count": 10,
133+
"metadata": {},
134+
"outputs": [
135+
{
136+
"data": {
137+
"text/plain": [
138+
"41.52"
139+
]
140+
},
141+
"execution_count": 10,
142+
"metadata": {},
143+
"output_type": "execute_result"
144+
}
145+
],
146+
"source": [
147+
"item.cloud_cover"
148+
]
149+
},
150+
{
151+
"cell_type": "code",
152+
"execution_count": 11,
153+
"metadata": {},
154+
"outputs": [
155+
{
156+
"name": "stdout",
157+
"output_type": "stream",
158+
"text": [
159+
"thumbnail: https://roda.sentinel-hub.com/sentinel-s2-l1c/tiles/9/V/XK/2017/10/13/0/preview.jpg (None)\n",
160+
"info: https://roda.sentinel-hub.com/sentinel-s2-l1c/tiles/9/V/XK/2017/10/13/0/tileInfo.json (None)\n",
161+
"metadata: https://roda.sentinel-hub.com/sentinel-s2-l1c/tiles/9/V/XK/2017/10/13/0/metadata.xml (None)\n",
162+
"tki: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/TKI.jp2 (image/jp2)\n",
163+
"B01: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B01.jp2 (image/jp2)\n",
164+
"B02: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B02.jp2 (image/jp2)\n",
165+
"B03: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B03.jp2 (image/jp2)\n",
166+
"B04: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B04.jp2 (image/jp2)\n",
167+
"B05: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B05.jp2 (image/jp2)\n",
168+
"B06: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B06.jp2 (image/jp2)\n",
169+
"B07: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B07.jp2 (image/jp2)\n",
170+
"B08: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B08.jp2 (image/jp2)\n",
171+
"B8A: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B08.jp2 (image/jp2)\n",
172+
"B09: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B09.jp2 (image/jp2)\n",
173+
"B10: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B10.jp2 (image/jp2)\n",
174+
"B11: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B11.jp2 (image/jp2)\n",
175+
"B12: https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B11.jp2 (image/jp2)\n"
176+
]
177+
}
178+
],
179+
"source": [
180+
"for asset_key in item.assets:\n",
181+
" asset = item.assets[asset_key]\n",
182+
" print('{}: {} ({})'.format(asset_key, asset.href, asset.media_type))"
183+
]
184+
},
185+
{
186+
"cell_type": "markdown",
187+
"metadata": {},
188+
"source": [
189+
"We can use the `to_dict()` method to convert an Asset, or any PySTAC object, into a dictionary:"
190+
]
191+
},
192+
{
193+
"cell_type": "code",
194+
"execution_count": 12,
195+
"metadata": {},
196+
"outputs": [
197+
{
198+
"data": {
199+
"text/plain": [
200+
"{'href': 'https://sentinel-s2-l1c.s3.amazonaws.com/tiles/9/V/XK/2017/10/13/0/B03.jp2',\n",
201+
" 'type': 'image/jp2',\n",
202+
" 'title': 'Band 3 (green)',\n",
203+
" 'eo:bands': [2]}"
204+
]
205+
},
206+
"execution_count": 12,
207+
"metadata": {},
208+
"output_type": "execute_result"
209+
}
210+
],
211+
"source": [
212+
"asset = item.assets['B03']\n",
213+
"asset.to_dict()"
214+
]
215+
},
216+
{
217+
"cell_type": "markdown",
218+
"metadata": {},
219+
"source": [
220+
"Here the asset uses the band information associated with it's item:"
221+
]
222+
},
223+
{
224+
"cell_type": "code",
225+
"execution_count": 13,
226+
"metadata": {},
227+
"outputs": [
228+
{
229+
"data": {
230+
"text/plain": [
231+
"{'name': 'B03',\n",
232+
" 'common_name': 'green',\n",
233+
" 'gsd': 10.0,\n",
234+
" 'center_wavelength': 0.56,\n",
235+
" 'full_width_half_max': 0.045}"
236+
]
237+
},
238+
"execution_count": 13,
239+
"metadata": {},
240+
"output_type": "execute_result"
241+
}
242+
],
243+
"source": [
244+
"asset.get_bands()[0].to_dict()"
245+
]
246+
}
247+
],
248+
"metadata": {
249+
"kernelspec": {
250+
"display_name": "Python [default]",
251+
"language": "python",
252+
"name": "python3"
253+
},
254+
"language_info": {
255+
"codemirror_mode": {
256+
"name": "ipython",
257+
"version": 3
258+
},
259+
"file_extension": ".py",
260+
"mimetype": "text/x-python",
261+
"name": "python",
262+
"nbconvert_exporter": "python",
263+
"pygments_lexer": "ipython3",
264+
"version": "3.6.5"
265+
}
266+
},
267+
"nbformat": 4,
268+
"nbformat_minor": 2
269+
}

0 commit comments

Comments
 (0)