Skip to content

Commit

Permalink
feat: Add proof of concept docs site BM-917 (#2990)
Browse files Browse the repository at this point in the history
#### Motivation

This adds an initial proof of concept of a documentation site. The
documentation is generated from a combination of static Markdown
documents; currently lightly modified from the existing files, plus a
few placeholders.

API documentation is generated from the typescript source code using
Typedoc. This is rendered to Markdown files using
typedoc-plugin-markdown, which is combined with the static Markdown
files to render the documentation site using MkDocs.

#### Modification

This is a rough proof of concept implementation, to be fleshed out in
subsequent PRs which will:
- Add more documentation.
- Improve the readability of the generated API docs (fix typographic
hierarchy and character escaping issues).
- Update the theme to match LINZ branding.

#### Checklist

- [ ] Tests updated
- [x] Docs updated
- [x] Issue linked in Title
  • Loading branch information
Andrew Jacombs authored Nov 6, 2023
1 parent e661201 commit cabccc7
Show file tree
Hide file tree
Showing 43 changed files with 219 additions and 16 deletions.
17 changes: 17 additions & 0 deletions .github/workflows/push.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@ jobs:
with:
package-manager: yarn

- name: Build docs
run: |
npx typedoc
docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material:9.4 build
- name: Store docs artifact
uses: actions/upload-artifact@v3
with:
name: docs
path: packages/landing/dist/docs

# pulls all tags (needed for lerna to correctly version)
- run: git fetch --depth=1 origin +refs/tags/*:refs/tags/* # see https://stackoverflow.com/a/60184319/9285308

Expand Down Expand Up @@ -85,6 +96,12 @@ jobs:
mask-aws-account-id: true
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}

- name: (Dev) Download docs artifact
uses: actions/download-artifact@v3
with:
name: docs
path: packages/landing/dist/docs

- name: (Dev) Deploy
run: |
npx lerna run bundle --stream
Expand Down
5 changes: 5 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Overview

## What is LINZ Basemaps?

A digital basemap provides a consistent background detail necessary to orient location and add to aesthetic appeal. Basemaps can be made up of streets, parcels, boundaries (country, regional, and city boundaries), shaded relief of a digital elevation model, waterways, hydrography, aerial and satellite imagery. Basemaps can be used as desktop, website or mobile phone application components, or as a 3rd party layers within a GIS or desktop mapping application.
4 changes: 4 additions & 0 deletions docs/developer-guide/API/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Ignore everything in this directory
*
# Except this file
!.gitignore
7 changes: 7 additions & 0 deletions docs/developer-guide/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Developer guide

Documentation of the Basemaps codebase for developers

- How to build
- Contributing guidelines
- TypeDoc API docs
4 changes: 0 additions & 4 deletions docs/imagery/README.md

This file was deleted.

8 changes: 8 additions & 0 deletions docs/operator-guide/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Basemaps operator guide

How to deploy your own instance of Basemaps

- How to run basemaps on your own imagery
- Simple CLI examples on how to serve tiffs from docker
- How to process imagery into more efficent formats
- Complex TIFF examples
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# COG Quality - Resampling with reprojecton and overview creation
# COG Quality

## Resampling with reprojecton and overview creation

creating COGs using a command very similar to

Expand Down Expand Up @@ -35,24 +37,24 @@ When creating COGs using the different resampling methods the output quality dif

Here are some overviews created using some of the different resampling methods:

![Resampling Quality](./images/quality__resampling-overview.webp)
![Resampling Quality](./static/quality__resampling-overview.webp)

### Lanczos

Provides quite a nice and crisp output

![Lanczos Overview](./images/quality__i6.lanczos.webp)
![Lanczos Overview](./static/quality__i6.lanczos.webp)

### Cubic
Creates weird artifacts around the edges

![Cubic Overview](./images/quality__i6.cubic.webp)
![Cubic Overview](./static/quality__i6.cubic.webp)

### Bilinear

looks blury

![Bilinear Overview](./images/quality__i6.bilinear.webp)
![Bilinear Overview](./static/quality__i6.bilinear.webp)


Using lanczos looks best for our overview creation.
Expand All @@ -67,13 +69,13 @@ Here are some higher resolution aerial imagery image 0 with different resampling

Creates a jaggeredness, look at the street markings and the edges of the buildings

![Lanczos](./images/quality__005_006_0_lanczos.webp)
![Lanczos](./static/quality__005_006_0_lanczos.webp)

### Bilinear

Creates a nice image

![Bilinear](./images/quality__005_006_0_bilinear.webp)
![Bilinear](./static/quality__005_006_0_bilinear.webp)


For our aerial imagery reprojection seems to be best done as bilinear, where as Overview creation seems to be best done as lanczos.
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,14 @@ gdaldem color-relief -co COMPRESS=lzw -co TILED=yes -co NUM_THREADS=ALL_CPUS -of
Relief shading with vector tiles the only imagery operation is "overlay", if any `white` exists in the relief shade it lightens the image

Base Image:
![Aerial imagery](./images/relief__aerial.webp)
![Aerial imagery](./static/relief__aerial.webp)

gdaldem hillshade:
![Aerial imagery](./images/relief__base.webp)
![Aerial imagery](./static/relief__base.webp)


Using default color ramp applys whites
![Lighten](./images/relief__lighten.webp)
![Lighten](./static/relief__lighten.webp)

Custom color ramp which only applys the darken

Expand All @@ -53,4 +53,4 @@ nv 0 0 0 0

`nv` - No value or NO_DATA set full alpha

![Lighten](./images/relief__darken.webp)
![Lighten](./static/relief__darken.webp)
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
7 changes: 7 additions & 0 deletions docs/user-guide/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# User guide

How to use the Basemaps service for end users.

- How to use basemaps.linz.govt.nz.
- Lots of examples similar to maplibre.
- Probably only care about WMTS/XYZ/style endpoints.
15 changes: 15 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
site_name: 'LINZ Basemaps'
docs_dir: './docs'
site_dir: './packages/landing/dist/docs'
theme:
name: 'material'
features:
- navigation.indexes
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: '__span'
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@
"lerna": "5.1.4",
"ospec": "^4.0.1",
"rimraf": "^3.0.0",
"sinon": "^13.0.1"
"sinon": "^13.0.1",
"typedoc": "^0.25.2",
"typedoc-plugin-markdown": "^4.0.0-next.25"
},
"workspaces": {
"packages": [
Expand Down
4 changes: 4 additions & 0 deletions packages/attribution/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/cli/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/cogify/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__test__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/config/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/geo/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/lambda-analytics/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/lambda-tiler/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/landing/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/linzjs-docker-command/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/linzjs-geojson/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/linzjs-metrics/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/server/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/shared/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/smoke/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/test.ts"]
}
4 changes: 4 additions & 0 deletions packages/sprites/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__test__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/tiler-sharp/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
4 changes: 4 additions & 0 deletions packages/tiler/typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"entryPoints": ["./src/**/*.ts"],
"exclude": ["./**/__tests__/*.ts"]
}
10 changes: 10 additions & 0 deletions typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"entryPoints": ["./packages/*"],
"entryPointStrategy": "packages",
"exclude": ["./packages/__tests__"],
"plugin": ["typedoc-plugin-markdown"],
"out": "./docs/developer-guide/API",
"outputFileStrategy": "modules",
"readme": "none",
"githubPages": false
}
62 changes: 62 additions & 0 deletions yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -2178,6 +2178,11 @@ ansi-escapes@^4.2.1:
resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304"
integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==

ansi-sequence-parser@^1.1.0:
version "1.1.1"
resolved "https://registry.yarnpkg.com/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz#e0aa1cdcbc8f8bb0b5bca625aac41f5f056973cf"
integrity sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==

ansi-styles@^3.2.1:
version "3.2.1"
resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d"
Expand Down Expand Up @@ -5065,6 +5070,11 @@ json5@^2.1.2:
resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.1.tgz#655d50ed1e6f95ad1a3caababd2b0efda10b395c"
integrity sha512-1hqLFMSrGHRHxav9q9gNjJ5EXznIxGVO09xQRrwplcS8qs28pZ8s8hupZAmqDwZUmVZ2Qb2jnyPOWcDH8m8dlA==

jsonc-parser@^3.2.0:
version "3.2.0"
resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76"
integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==

jsonfile@^6.0.1:
version "6.0.1"
resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-6.0.1.tgz#98966cba214378c8c84b82e085907b40bf614179"
Expand Down Expand Up @@ -5347,6 +5357,11 @@ lru-cache@^7.4.4, lru-cache@^7.7.1:
resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-7.10.1.tgz#db577f42a94c168f676b638d15da8fb073448cab"
integrity sha512-BQuhQxPuRl79J5zSXRP+uNzPOyZw2oFI9JLRQ80XswSvg21KMKNtQza9eF42rfI/3Z40RvzBdXgziEkudzjo8A==

lunr@^2.3.9:
version "2.3.9"
resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1"
integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==

make-dir@^2.1.0:
version "2.1.0"
resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-2.1.0.tgz#5f0310e18b8be898cc07009295a30ae41e91e6f5"
Expand Down Expand Up @@ -5471,6 +5486,11 @@ maplibre-gl@^2.1.9:
tinyqueue "^2.0.3"
vt-pbf "^3.1.3"

marked@^4.3.0:
version "4.3.0"
resolved "https://registry.yarnpkg.com/marked/-/marked-4.3.0.tgz#796362821b019f734054582038b116481b456cf3"
integrity sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==

memoize-one@^5.0.0:
version "5.2.1"
resolved "https://registry.yarnpkg.com/memoize-one/-/memoize-one-5.2.1.tgz#8337aa3c4335581839ec01c3d594090cebe8f00e"
Expand Down Expand Up @@ -5630,6 +5650,13 @@ minimatch@^5.0.1:
dependencies:
brace-expansion "^2.0.1"

minimatch@^9.0.3:
version "9.0.3"
resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.3.tgz#a6e00c3de44c3a542bfaae70abfc22420a6da825"
integrity sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==
dependencies:
brace-expansion "^2.0.1"

[email protected]:
version "4.1.0"
resolved "https://registry.yarnpkg.com/minimist-options/-/minimist-options-4.1.0.tgz#c0655713c53a8a2ebd77ffa247d342c40f010619"
Expand Down Expand Up @@ -7415,6 +7442,16 @@ shelljs@^0.8.3:
interpret "^1.0.0"
rechoir "^0.6.2"

shiki@^0.14.1:
version "0.14.5"
resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.5.tgz#375dd214e57eccb04f0daf35a32aa615861deb93"
integrity sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw==
dependencies:
ansi-sequence-parser "^1.1.0"
jsonc-parser "^3.2.0"
vscode-oniguruma "^1.7.0"
vscode-textmate "^8.0.0"

signal-exit@^3.0.0, signal-exit@^3.0.2:
version "3.0.2"
resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.2.tgz#b5fdc08f1287ea1178628e415e25132b73646c6d"
Expand Down Expand Up @@ -8138,6 +8175,21 @@ typedarray@^0.0.6:
resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=

typedoc-plugin-markdown@^4.0.0-next.25:
version "4.0.0-next.25"
resolved "https://registry.yarnpkg.com/typedoc-plugin-markdown/-/typedoc-plugin-markdown-4.0.0-next.25.tgz#df7c487db2806f2782ea2a5c288874229454439d"
integrity sha512-OAucyztjyTcJhpyH8lK3r6W/9lGYxRnEphmphAi8CLL4pBqzA9A00OaOWt4ybkcFBnB8zNIZ4SGCz1sk9NBA3g==

typedoc@^0.25.2:
version "0.25.2"
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.2.tgz#39f525c28b6eb61da54dda4ec6b1500df620bed8"
integrity sha512-286F7BeATBiWe/qC4PCOCKlSTwfnsLbC/4cZ68oGBbvAqb9vV33quEOXx7q176OXotD+JdEerdQ1OZGJ818lnA==
dependencies:
lunr "^2.3.9"
marked "^4.3.0"
minimatch "^9.0.3"
shiki "^0.14.1"

typescript@^4.9.4:
version "4.9.4"
resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.4.tgz#a2a3d2756c079abda241d75f149df9d561091e78"
Expand Down Expand Up @@ -8272,6 +8324,16 @@ varint@^5.0.2:
resolved "https://registry.yarnpkg.com/varint/-/varint-5.0.2.tgz#5b47f8a947eb668b848e034dcfa87d0ff8a7f7a4"
integrity sha512-lKxKYG6H03yCZUpAGOPOsMcGxd1RHCu1iKvEHYDPmTyq2HueGhD73ssNBqqQWfvYs04G9iUFRvmAVLW20Jw6ow==

vscode-oniguruma@^1.7.0:
version "1.7.0"
resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b"
integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==

vscode-textmate@^8.0.0:
version "8.0.0"
resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-8.0.0.tgz#2c7a3b1163ef0441097e0b5d6389cd5504b59e5d"
integrity sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==

vt-pbf@^3.1.3:
version "3.1.3"
resolved "https://registry.yarnpkg.com/vt-pbf/-/vt-pbf-3.1.3.tgz#68fd150756465e2edae1cc5c048e063916dcfaac"
Expand Down

0 comments on commit cabccc7

Please sign in to comment.