Setup documentation using mkdocs (#133)

* add setup files from dolphin mkdocs

* remove ds store

* remove raider from requirements/conda-env.yml

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+mkdocs:
+  configuration: mkdocs.yml
+
+conda:
+  environment: docs/conda-env.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/conda-env.yml

@@ -0,0 +1,18 @@
+name: compass-docs-env
+channels:
+  - conda-forge
+dependencies:
+  - python[version='>=3.9']
+  - numpy
+  - lxml
+  - gdal[version='>=3']
+  - pandas
+  - pyproj
+  - pysolid
+  - pytest
+  - ruamel.yaml
+  - scipy
+  - yamale
+  - h5py
+  - shapely
+  - requests

docs/gen_ref_pages.py

@@ -0,0 +1,32 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("src").rglob("*.py")):
+    module_path = path.relative_to("src").with_suffix("")
+    doc_path = path.relative_to("src").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/summary.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/getting-started.md

@@ -0,0 +1,47 @@
+## Install
+
+The following will install COMPASS into a conda environment.
+
+1. Download source code:
+
+```bash
+git clone https://github.com/opera-adt/COMPASS.git
+```
+
+2. Install dependencies:
+
+```bash
+conda install -c conda-forge --file COMPASS/requirements.txt
+python -m pip install git+https://github.com/opera-adt/s1-reader.git
+```
+
+3. Install `COMPASS` via pip:
+
+```bash
+# run "pip install -e" to install in development mode
+python -m pip install ./COMPASS
+``` 
+
+## Usage
+
+The following commands generate coregistered SLC in radar or geo-coordinates from terminal:
+
+```bash
+s1_cslc.py --grid geo   <path to s1_cslc_geo   yaml file>
+s1_cslc.py --grid radar <path to s1_cslc_radar yaml file for reference burst>
+s1_cslc.py --grid radar <path to s1_cslc_radar yaml file for secondary burst>
+```
+
+## Creating Documentation
+
+
+We use [MKDocs](https://www.mkdocs.org/) to generate the documentation.
+The reference documentation is generated from the code docstrings using [mkdocstrings](mkdocstrings.github.io/).
+
+When adding new documentation, you can build and serve the documentation locally using:
+
+```
+mkdocs serve
+```
+then open http://localhost:8000 in your browser.
+Creating new files or updating existing files will automatically trigger a rebuild of the documentation while `mkdocs serve` is running.

docs/index.md

@@ -0,0 +1,13 @@
+# COMPASS Documentation
+
+
+## Table Of Contents
+
+<!-- The documentation follows the project documentation as described the [Diátaxis documentation framework](https://diataxis.fr/)
+-->
+
+1. [Getting started](./getting-started.md)
+1. [Tutorials](tutorials.md)
+1. [How-To Guides](how-to-guides.md)
+1. [Code Reference](reference/summary.md)
+1. [Background theory](background-theory.md)

docs/javascripts/mathjax.js

@@ -0,0 +1,18 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+  };
+
+  document$.subscribe(() => {
+
+
+  MathJax.typesetPromise()
+})

docs/requirements.txt

@@ -0,0 +1,8 @@
+# mkdocs requirements
+mkdocs
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-material
+mkdocs-section-index
+mkdocstrings[python]
+pymdown-extensions

docs/tutorials.md

@@ -0,0 +1,17 @@
+This part of the project documentation will contain step-by-step instructions for learning about generating displacement using COMPASS.
+
+<!-- **learning-oriented** approach. You'll learn how to
+get started with the code in this project.
+
+**Note:** Expand this section by considering the
+following points:
+
+- Help newcomers with getting started
+- Teach readers about your library by making them
+    write code
+- Inspire confidence through examples that work for
+    everyone, repeatably
+- Give readers an immediate sense of achievement
+- Show concrete examples, no abstractions
+- Provide the minimum necessary explanation
+- Avoid any distractions -->

mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: Documentation for COMPASS
+
+theme:
+  name: "material"
+  palette:
+    # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#primary-color
+    primary: "blue"
+  # favicon: img/favicon.ico
+  # logo: img/apple-touch-icon.png
+  highlightjs: true
+
+
+plugins:
+- search
+# plugin suggestions from here: https://mkdocstrings.github.io/recipes/
+- gen-files:
+    scripts:
+    - docs/gen_ref_pages.py
+# https://github.com/oprypin/mkdocs-literate-nav
+- literate-nav:
+    nav_file: summary.md
+# https://mkdocstrings.github.io/python/usage/
+- mkdocstrings:
+    handlers:
+      python:
+        paths: [src]
+        options:
+          docstring_style: numpy
+          members_order: alphabetical # source
+
+
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+
+watch:
+- src/
+
+nav:
+- index.md
+- getting-started.md
+- tutorials.md
+- how-to-guides.md
+# https://mkdocstrings.github.io/recipes/#generate-a-literate-navigation-file
+# trailing slash: that mkdocs-literate-nav knows a summary.md file is in that folder.
+- Code Reference: reference/
+- background-theory.md

requirements.txt

@@ -8,7 +8,6 @@ pandas
 pyproj
 pysolid
 pytest
-raider
 ruamel.yaml
 scipy
 yamale