Static Documentation for v0.1

.gitignore

@@ -18,6 +18,8 @@ logs/
 # Data files and folders
 data/**
 !data/**/
+**/*/.gif
+**/*/.png
 
 # Distribution / packaging
 .Python

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
   rev: v4.5.0
   hooks:
     - id: check-added-large-files
+      args: [ '--maxkb=512', '--enforce-all' ]
     - id: check-yaml
     - id: end-of-file-fixer
     - id: trailing-whitespace

docs/README.md

@@ -0,0 +1,20 @@
+# Clay Model Documentation
+
+This Documentation uses [Jupyter Book](https://jupyterbook.org/intro.html).
+
+Install it with:
+```bash
+pip install -U jupyter-book
+```
+
+Then build it with:
+```bash
+jupyter-book build docs/
+```
+
+You can preview the site locally with:
+```bash
+python -m http.server --directory _build/html
+```
+
+There is a GitHub Action on `./github/workflows/deploy-docs.yml` that builds the site and pushes it to GitHub Pages.

docs/_config.yml

@@ -4,11 +4,14 @@
 title: Clay Foundation Model
 author: Clay Foundation
 logo: logo.png
+only_build_toc_files: true
 
-# Force re-execution of notebooks on each build.
+# Only execution notebooks with no output cells on each build.
 # See https://jupyterbook.org/content/execute.html
 execute:
-  execute_notebooks: force
+  execute_notebooks: cache
+  exclude_patterns:
+    - clay-v0-*.ipynb
 
 # Define the name of the latex output file for PDF builds
 latex:

docs/_toc.yml

@@ -2,12 +2,20 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: intro
+root: index
 parts:
+- caption: Release notes
+  chapters:
+    - title: Software release notes
+      file: changelog
+    - title: Model release notes
+      file: specification
 - caption: Getting Started
   chapters:
     - title: Installation
       file: installation
+    - title: Basic Use
+      file: basic_use
 - caption: Data Preparation
   chapters:
     - title: Creating datacubes
@@ -22,13 +30,19 @@ parts:
       file: model_embeddings
     - title: Finetuning
       file: model_finetuning
-- caption: Reference Documentation
+- caption: Tutorials
   chapters:
-    - title: Changelog
-      file: changelog
+    - title: Generative AI for pixel reconstruction
+      file: clay-v0-reconstruction
+    - title: Create location embeddings
+      file: clay-v0-location-embeddings
+    - title: Interpolating images in embedding space
+      file: clay-v0-interpolation
 - caption: About Clay
   chapters:
     - title: GitHub
       url: https://github.com/Clay-foundation
     - title: LinkedIn
       url: https://www.linkedin.com/company/made-with-clay
+    - title: Website
+      url: https://madewithclay.org

docs/basic_use.md

@@ -0,0 +1,42 @@
+# Basic Use
+
+### Running jupyter lab
+
+    mamba activate claymodel
+    python -m ipykernel install --user --name claymodel  # to install virtual env properly
+    jupyter kernelspec list --json                       # see if kernel is installed
+    jupyter lab &
+
+
+### Running the model
+
+The neural network model can be ran via
+[LightningCLI v2](https://pytorch-lightning.medium.com/introducing-lightningcli-v2supercharge-your-training-c070d43c7dd6).
+To check out the different options available, and look at the hyperparameter
+configurations, run:
+
+    python trainer.py --help
+    python trainer.py test --print_config
+
+To quickly test the model on one batch in the validation set:
+
+    python trainer.py validate --trainer.fast_dev_run=True
+
+To train the model for a hundred epochs:
+
+    python trainer.py fit --trainer.max_epochs=100
+
+To generate embeddings from the pretrained model's encoder on 1024 images
+(stored as a GeoParquet file with spatiotemporal metadata):
+
+    python trainer.py predict --ckpt_path=checkpoints/last.ckpt \
+                              --data.batch_size=1024 \
+                              --data.data_dir=s3://clay-tiles-02 \
+                              --trainer.limit_predict_batches=1
+
+More options can be found using `python trainer.py fit --help`, or at the
+[LightningCLI docs](https://lightning.ai/docs/pytorch/2.1.0/cli/lightning_cli.html).
+
+## Advanced
+
+See [Readme](https://github.com/Clay-foundation/model/blob/v0.0.1/README.md) on model root for more details.

docs/changelog.md

@@ -1,6 +1,11 @@
-# Changelog
+(software_release)=
+# Code Model release v0.0.1
+
+This changelog is a summary of the changes to the source code of the Clay model.
+Released on 2024/01/12.
+
+> For release notes for the trained model, see [](model_release)
 
-## Release v0.0.1 (2024/01/12)
 
 ### 💫 Highlights