Skip to content

Commit 4db9a18

Browse files
JuLeeAtPlanetcholmesjreiberkyle
authored
Documentation incremental update: global architecture and getting-started experience (GSX) (planetlabs#747)
* describing getting started docs * adding custom theme for landing pg & GSX * moved doc files into buckets * more doc file moves and content chunking * WIP Rough Quick Start Draft * More Doc File moves * mkdocs nav tweeks * changed doc pages to use title tag * updated footer & watch custom_theme dir * WIP: typo fix * reorg'd files * WIP GSX content * WIP quick start content * Update docs/get-started/quick-start-guide.md Co-authored-by: Chris Holmes <[email protected]> * Update docs/get-started/quick-start-guide.md Co-authored-by: Chris Holmes <[email protected]> * Update docs/get-started/quick-start-guide.md Co-authored-by: Chris Holmes <[email protected]> * WIP: typo fix * WIP: minor lang * Update docs/get-started/quick-start-guide.md Co-authored-by: Jennifer Reiber Kyle <[email protected]> * added mockups to design doc * Update docs/get-started/get-your-planet-account.md Co-authored-by: Chris Holmes <[email protected]> * Update docs/get-started/quick-start-guide.md Co-authored-by: Chris Holmes <[email protected]> Co-authored-by: Chris Holmes <[email protected]> Co-authored-by: Jennifer Reiber Kyle <[email protected]>
1 parent 4c0623d commit 4db9a18

27 files changed

+1382
-476
lines changed

‎design-docs/content-gsx-notes.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Create a Getting Started Experience (GSX)
2+
3+
We'd like to make sure folks who come to the docs site can get started easily. We'd like them to know how to:
4+
5+
* Get an API key
6+
* Authenticate against the service
7+
* Search and download data using the CLI
8+
* Search and download data using the Python calls
9+
* Find key content and support
10+
11+
# A clear top nav will help with the GSX
12+
13+
## Here are some mockups of the global nav changes:
14+
15+
### Home splash screen
16+
17+
<img src="./img/home_1.png"
18+
style="
19+
display: block;
20+
margin-left: auto;
21+
margin-right: auto;
22+
width:50%;
23+
"
24+
alt="home mock" >
25+
26+
<img src="./img/home_2.png"
27+
style="
28+
display: block;
29+
margin-left: auto;
30+
margin-right: auto;
31+
width:50%;
32+
"
33+
alt="home mock" >
34+
35+
<img src="./img/home_3.png"
36+
style="
37+
display: block;
38+
margin-left: auto;
39+
margin-right: auto;
40+
width:50%;
41+
"
42+
alt="home mock" >
43+
44+
### Getting started landing page
45+
46+
<img src="./img/getting-started-docs.png"
47+
style="
48+
display: block;
49+
margin-left: auto;
50+
margin-right: auto;
51+
width:50%;
52+
"
53+
alt="Getting started landing page mock" >
54+
55+
### Python landing page
56+
57+
<img src="./img/python-docs.png"
58+
style="
59+
display: block;
60+
margin-left: auto;
61+
margin-right: auto;
62+
width:50%;
63+
"
64+
alt="Python landing page mock" >
65+
66+
### CLI landing page
67+
68+
<img src="./img/no-code-cli-docs.png"
69+
style="
70+
display: block;
71+
margin-left: auto;
72+
margin-right: auto;
73+
width:50%;
74+
"
75+
alt="No Code CLI landing page mock" >
76+
77+
### Resources landing page
78+
79+
<img src="./img/resources-docs.png"
80+
style="
81+
display: block;
82+
margin-left: auto;
83+
margin-right: auto;
84+
width:50%;
85+
"
86+
alt="Resources landing page mock" >
87+
88+
## Add a clear top nav to mkdocs materials using a custom home page
89+
90+
" if the theme.custom_dir configuration value is used in combination with an existing theme, the theme.custom_dir can be used to replace only specific parts of a built-in theme"
91+
92+
"built-in themes are implemented in a base.html file, which main.html extends"
93+
94+
[mkdocs.org dev-guide themes ](https://www.mkdocs.org/dev-guide/themes/)
95+
96+
### Create a custom theme
97+
98+
1. Create a main jinga template file that is not a child of docs, as in:
99+
100+
```custom_theme/main.html```
101+
102+
2. Add that custom dir to the mkdocs.yml file, under `theme`:
103+
104+
```custom_dir: 'custom_theme/'```
105+
106+
3. Add metadata to docs/index.md:
107+
108+
```
109+
---
110+
title: Title
111+
template: home.html
112+
---
113+
```
114+
115+
116+
### Notes
117+
118+
[Developing Themes : A guide to creating and distributing custom themes.](https://www.mkdocs.org/dev-guide/themes/)
119+
120+
[Steps to creating a similar homepage](https://github.com/squidfunk/mkdocs-material/issues/1996#issuecomment-855086383)
121+
122+
[Template Designer Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/)
123+
124+
125+
### Open questions
126+
127+
#### will we ever distribute theme? If so, then:
128+
129+
["when a theme is packaged up for distribution, and loaded using the theme.name configuration option, then a mkdocs_theme.yml file is required for the theme."](https://www.mkdocs.org/dev-guide/themes/)

‎docs/cli-concepts.md renamed to ‎docs/cli/cli-concepts.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Command-line Interface (CLI) Concepts
1+
---
2+
title: Command-line Interface (CLI) Concepts
3+
---
24

35
Planet's command-line interface is built of composable pieces that combine in powerful ways.
46
To take full advantage of all that Planet's CLI offers there are a few concepts and tools

‎docs/cli/cli-guide.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: No-Code CLI Guide
3+
---
4+
5+
## Authentication and your API key
6+
7+
The `auth` command allows the CLI to authenticate with Planet servers. Before
8+
any other command is run, the CLI authentication should be initiated with
9+
10+
```console
11+
$ planet auth init
12+
```
13+
14+
!!!note Note
15+
For information on how to confirm your Planet Account, see [Get a Planet Account](../../get-started/get-your-planet-account/).
16+
17+
You can store the API key associated with your account in an environment variable, e.g.
18+
for passing into a Docker instance:
19+
20+
```console
21+
$ export PL_API_KEY=$(planet auth value)
22+
```
23+
24+
The `auth value` returned is the same as the API key in your [Account](https://account.planet.com/) under My Settings. You can also retrieve it when viewing scenes in Planet Explorer by selecting "API {:}" at the bottom of the daily scene panel.
25+
26+
## Collecting Results
27+
28+
Some API calls, such as searching for imagery and listing orders, return a
29+
varying, and potentially large, number of results. These API responses are
30+
paged. The SDK manages paging internally and the associated cli commands
31+
output the results as a sequence. These results can be converted to a JSON blob
32+
using the `collect` command. When the results
33+
represent GeoJSON features, the JSON blob is a GeoJSON FeatureCollection.
34+
Otherwise, the JSON blob is a list of the individual results.
35+
36+
```console
37+
$ planet data search PSScene filter.json | planet collect -
38+
```
39+
40+
contents of `filter.json`:
41+
42+
```json
43+
{
44+
"type":"DateRangeFilter",
45+
"field_name":"acquired",
46+
"config":{
47+
"gt":"2019-12-31T00:00:00Z",
48+
"lte":"2020-01-31T00:00:00Z"
49+
}
50+
}
51+
```
52+
53+
## Orders API
54+
55+
Most `orders` cli commands are simple wrappers around the
56+
[Planet Orders API](https://developers.planet.com/docs/orders/reference/#tag/Orders)
57+
commands.
58+
59+
60+
### Create Order File Inputs
61+
62+
Creating an order supports JSON files as inputs and these need to follow certain
63+
formats.
64+
65+
66+
#### --cloudconfig
67+
The file given with the `--cloudconfig` option should contain JSON that follows
68+
the options and format given in
69+
[Delivery to Cloud Storage](https://developers.planet.com/docs/orders/delivery/#delivery-to-cloud-storage).
70+
71+
An example would be:
72+
73+
Example: `cloudconfig.json`
74+
```
75+
{
76+
"amazon_s3": {
77+
"aws_access_key_id": "aws_access_key_id",
78+
"aws_secret_access_key": "aws_secret_access_key",
79+
"bucket": "bucket",
80+
"aws_region": "aws_region"
81+
},
82+
"archive_type": "zip"
83+
}
84+
```
85+
86+
#### --clip
87+
The file given with the `--clip` option should contain valid [GeoJSON](https://geojson.org/).
88+
It can be a Polygon geometry, a Feature, or a FeatureClass. If it is a FeatureClass,
89+
only the first Feature is used for the clip geometry.
90+
91+
Example: `aoi.geojson`
92+
```
93+
{
94+
"type": "Polygon",
95+
"coordinates": [
96+
[
97+
[
98+
37.791595458984375,
99+
14.84923123791421
100+
],
101+
[
102+
37.90214538574219,
103+
14.84923123791421
104+
],
105+
[
106+
37.90214538574219,
107+
14.945448293647944
108+
],
109+
[
110+
37.791595458984375,
111+
14.945448293647944
112+
],
113+
[
114+
37.791595458984375,
115+
14.84923123791421
116+
]
117+
]
118+
]
119+
}
120+
```
121+
122+
#### --tools
123+
The file given with the `--tools` option should contain JSON that follows the
124+
format for a toolchain, the "tools" section of an order. The toolchain options
125+
and format are given in
126+
[Creating Toolchains](https://developers.planet.com/docs/orders/tools-toolchains/#creating-toolchains).
127+
128+
Example: `tools.json`
129+
```
130+
[
131+
{
132+
"toar": {
133+
"scale_factor": 10000
134+
}
135+
},
136+
{
137+
"reproject": {
138+
"projection": "WGS84",
139+
"kernel": "cubic"
140+
}
141+
},
142+
{
143+
"tile": {
144+
"tile_size": 1232,
145+
"origin_x": -180,
146+
"origin_y": -90,
147+
"pixel_size": 2.7056277056e-05,
148+
"name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}"
149+
}
150+
}
151+
]
152+
```
153+
154+
## Data API
155+
156+
Most `data` cli commands are simple wrappers around the
157+
[Planet Data API](https://developers.planet.com/docs/apis/data/reference/)
158+
commands with the only difference being the addition of functionality to create
159+
a search filter, activate an asset, poll for when activation is complete, and
160+
download the asset.
161+
162+
163+
### Filter
164+
165+
The search-related Data API CLI commands require a search filter. The filter
166+
CLI command provides basic functionality for generating this filter. For
167+
more advanced functionality, use the Python API `data_filter` commands.
168+
169+
The following is an example of using the filter command to generate a filter
170+
that specifies an aquired date range and AOI:
171+
172+
```console
173+
$ planet data filter \
174+
--date-range acquired gte 2022-01-01 \
175+
--date-range acquired lt 2022-02-01 \
176+
--geom aoi.json
177+
```
178+
179+
This can be fed directly into a search command e.g.:
180+
181+
```console
182+
$ planet data filter --geom aoi.json | planet data search PSScene -
183+
```

‎docs/cli-plus-tutorial.md renamed to ‎docs/cli/cli-plus-tutorial.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: More CLI Tips & Tricks
3+
---
4+
15
## About
26

37
This document shows off a range of more advanced command-line workflows, making use of a wider range

‎docs/cli.md renamed to ‎docs/cli/cli-reference.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# CLI Reference
1+
---
2+
title: CLI Reference
3+
---
24

35
This page provides documentation for our command line tools.
46

‎docs/cli-tutorial.md renamed to ‎docs/cli/cli-tutorial.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
---
2+
title: CLI Tutorial
3+
---
14

25
## About
36

@@ -16,7 +19,7 @@ We start with the `auth` package of tools, to ensure you can get started.
1619
#### Initialize
1720

1821
The main way to initialize the Planet CLI is to use `init`, which will prompt
19-
you for your Planet username and password, and then store your API key.
22+
you for your Planet user name and password, and then store your API key.
2023

2124
```console
2225
planet auth init
@@ -712,7 +715,7 @@ planet orders request SkySatCollect analytic --name "SkySat Latest" \
712715
```
713716

714717
Or get the 5 latest cloud free images in an area and create an order that clips to that area, using
715-
[geometry.geojson](data/geometry.json) from above:
718+
[geometry.geojson](data/geometry.geojson) from above:
716719

717720
```console
718721
ids=`planet data filter --geom geometry.geojson --range clear_percent gt 90 | planet data \

0 commit comments

Comments
 (0)