Add ADRs to documentation

Author: duckontheweb

.adr-dir

@@ -0,0 +1 @@
+docs/source/design

docs/source/conf.py

@@ -38,6 +38,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    'recommonmark'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/design/0001-record-architecture-decisions.md

@@ -0,0 +1,21 @@
+# 1. Record architecture decisions
+
+Date: 2021-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as 
+[described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's 
+[adr-tools](https://github.com/npryce/adr-tools).

docs/source/design/0002-choose-stac-library.md

@@ -0,0 +1,56 @@
+# 2. Choose STAC library
+
+Date: 2021-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+We would like to use an existing Python library for working with STAC objects as Python objects. Ideally this library 
+will meet the following requirements:
+
+* **Actively maintained** to ensure that it is up-to-date with the latest STAC spec
+* **Well-documented** to reduce the documentation burden for this library
+* **Easily extensible** to allow us to take advantage of existing STAC object functionality
+
+The 2 most obvious choices for Python STAC clients are 
+[`PySTAC`](https://github.com/stac-utils/pystac) and [`sat-stac`](https://github.com/sat-utils/sat-stac). 
+
+### `PySTAC`
+
+`PySTAC` is an actively maintained STAC client for Python 3. Its last release was less than 2 months ago and its last 
+commit was less than 2 weeks ago. It has had 15 contributors within the last year and it supports the latest release 
+candidate for the STAC spec (as well as previous releases). `PySTAC` hosts 
+[documentation on ReadTheDocs](https://pystac.readthedocs.io/en/latest/) that includes a description of programming 
+concepts related to the library, quickstart instructions, tutorials, and an API reference.
+
+`PySTAC` supports both reading and writing of STAC objects. Extending `PySTAC` classes through inheritance is made a 
+bit more difficult by the fact that some class methods (like ``from_dict``) have references to specific classes 
+(like ``Catalog``) rather than using the ``cls`` argument. This will require us to overwrite some of these methods to 
+implement inheritance. It has robust support for traversing catalogs using links. There is no existing support for the 
+STAC API spec in `PySTAC` or any related tooling.
+
+### `sat-stac`
+
+`sat-stac` is an actively maintained STAC client for Python 3. Its last release was less than 2 months ago and its 
+last commit was at that same time. It has had 2 contributors within the last year and it supports the latest release 
+candidate for the STAC spec (as well as previous releases). `sat-stac` has installation documented in the GitHub repo's 
+main README and has 2 tutorials in the form of Jupyter Notebooks in that repo. 
+
+`sat-stac` supports reading STAC catalogs (support for writing STAC catalogs was removed in v0.4.0). There is also an 
+existing library for working with STAC API - Item Search results called 
+[sat-search](https://github.com/sat-utils/sat-search) that uses `sat-stac` as its backend. 
+
+## Decision
+
+We will use `PySTAC` as our "backend" for working with STAC objects in Python. While both libraries are well-maintained, 
+`PySTAC` has more thorough documentation and seems to be more widely supported through community contribution. 
+
+## Consequences
+
+We will need to create our own implementation of a STAC API - Item Search client since there is not existing tooling 
+based on `PySTAC`. We will be able to point to the hosted documentation for `PySTAC` to guide users through existing 
+functionality for navigating STAC Catalogs. Special care should be taken to ensure that we do not break any of 
+`PySTAC`'s functionality through inheritance.

docs/source/design_decisions.rst

@@ -0,0 +1,12 @@
+Design Decisions
+================
+
+`Architectural Design Records (ADRs)
+<https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>`__ for major design decisions related to the
+library.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   design/*

docs/source/index.rst

@@ -65,6 +65,17 @@ with ``stac_api_client``.
 
    api
 
+Design Decisions
+----------------
+
+We document significant design decisions using Architectural Design Records (ADRs), as described by Michael Nygard
+`here <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>`__.
+
+.. toctree::
+   :maxdepth: 2
+
+   design_decisions
+
 
 Indices and tables
 ==================

poetry.lock

@@ -41,6 +41,7 @@ pytest-cov = "^2.11.1"
 pytest-recording = "^0.11.0"
 isort = "^5.7.0"
 vulture = "^2.3"
+recommonmark = "^0.7.1"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]