Add outline of doc pages to consdb/doc/

lsst-dm · Oct 4, 2024 · d31a958 · d31a958
1 parent 8cd8957
commit d31a958
Show file tree

Hide file tree

Showing 24 changed files with 164 additions and 1 deletion.
diff --git a/doc/conf.py b/doc/conf.py
@@ -1,6 +1,6 @@
 """Sphinx configuration file for an LSST stack package.
 
-This configuration only affects single-package Sphinx documenation builds.
+This configuration only affects single-package Sphinx documentation builds.
 """
 
 from documenteer.conf.guide import *  # noqa: F403,F401
diff --git a/doc/contributor-guide/adding-columns.rst b/doc/contributor-guide/adding-columns.rst
@@ -0,0 +1,6 @@
+###############
+Adding Columns
+###############
+
+* Values should be usefully summarized
+* Try to make everything into some kind of scalar
diff --git a/doc/contributor-guide/adding-tables.rst b/doc/contributor-guide/adding-tables.rst
@@ -0,0 +1,8 @@
+##############
+Adding Tables
+##############
+
+* Each source of data should have its own table(s)
+* Each dimension combination (exposure, visit, exposure+detector, visit+detector, etc.) should have its own table(s)
+* Normalize when possible
+* De-normalize via views to make querying easier
diff --git a/doc/contributor-guide/index.rst b/doc/contributor-guide/index.rst
@@ -0,0 +1,10 @@
+##################
+Contributor Guide
+##################
+
+.. toctree::
+   :maxdepth: 1
+
+   adding-tables
+   adding-columns
+   inserting-information
diff --git a/doc/contributor-guide/inserting-information.rst b/doc/contributor-guide/inserting-information.rst
@@ -0,0 +1,10 @@
+#####################
+Inserting Information
+#####################
+
+* Sasquatch
+    * REST API
+    * Direct Kafka messages
+
+* ConsDB client library in summit_utils
+* ConsDB REST API
diff --git a/doc/developer-guide/building-artifacts.rst b/doc/developer-guide/building-artifacts.rst
@@ -0,0 +1,6 @@
+##################
+Building Artifacts
+##################
+
+* Dockerfiles
+* GitHub Actions workflows
diff --git a/doc/developer-guide/consdbclient-summit-utils.rst b/doc/developer-guide/consdbclient-summit-utils.rst
@@ -0,0 +1,5 @@
+############################
+ConsDbClient in summit_utils
+############################
+
+How to write and test code in summit_utils for ConsDbClient
diff --git a/doc/developer-guide/documentation.rst b/doc/developer-guide/documentation.rst
@@ -0,0 +1,6 @@
+#############
+Documentation
+#############
+
+* This Site
+* Other Documentation
diff --git a/doc/developer-guide/index.rst b/doc/developer-guide/index.rst
@@ -0,0 +1,12 @@
+#################
+Developer Guide
+#################
+
+.. toctree::
+   :maxdepth: 1
+
+   repository-structure
+   building-artifacts
+   consdbclient-summit-utils
+   standards-practices
+   documentation
diff --git a/doc/developer-guide/repository-structure.rst b/doc/developer-guide/repository-structure.rst
@@ -0,0 +1,5 @@
+####################
+Repository Structure
+####################
+
+Each of the services in their own directory (coming soon)
diff --git a/doc/developer-guide/standards-practices.rst b/doc/developer-guide/standards-practices.rst
@@ -0,0 +1,5 @@
+#######################
+Standards and Practices
+#######################
+
+Standards and practices
diff --git a/doc/index.rst b/doc/index.rst
@@ -14,3 +14,6 @@ Documentation
     :maxdepth: 1
 
     user-guide/index
+    contributor-guide/index
+    developer-guide/index
+    operator-guide/index
diff --git a/doc/operator-guide/deployment.rst b/doc/operator-guide/deployment.rst
@@ -0,0 +1,6 @@
+###########
+Deployment
+###########
+
+* Database
+* REST API Server
diff --git a/doc/operator-guide/index.rst b/doc/operator-guide/index.rst
@@ -0,0 +1,11 @@
+##############
+Operator Guide
+##############
+
+.. toctree::
+   :maxdepth: 1
+
+   runbook
+   schema-migration-process
+   deployment
+   monitoring
diff --git a/doc/operator-guide/monitoring.rst b/doc/operator-guide/monitoring.rst
@@ -0,0 +1,6 @@
+###########
+Monitoring
+###########
+
+* Database
+* REST API Server
diff --git a/doc/operator-guide/runbook.rst b/doc/operator-guide/runbook.rst
@@ -0,0 +1,5 @@
+########
+RunBook
+########
+
+Maybe from ConsDb Usage Confluence page?
diff --git a/doc/operator-guide/schema-migration-process.rst b/doc/operator-guide/schema-migration-process.rst
@@ -0,0 +1,9 @@
+########################
+Schema Migration Process
+########################
+
+* Add columns to sdm_schemas
+* Create alembic migration
+* Test migration and code to populate the new columns/tables at TTS/BTS if Summit schema is changing
+* Deploy migration in synchrony at Summit (if necessary), USDF, and Prompt Release (if necessary)
+* Deploy code to populate at Summit and/or USDF
diff --git a/doc/user-guide/consdb-client-library-in-summit-utils.rst b/doc/user-guide/consdb-client-library-in-summit-utils.rst
@@ -0,0 +1,5 @@
+######################################
+ConsDB Client Library in summit_utils
+######################################
+
+Querying using ConsDbClient
diff --git a/doc/user-guide/consdb-rest-api.rst b/doc/user-guide/consdb-rest-api.rst
@@ -0,0 +1,5 @@
+################
+ConsDB REST API
+################
+
+Link to Swagger
diff --git a/doc/user-guide/description-and-goals.rst b/doc/user-guide/description-and-goals.rst
@@ -0,0 +1,5 @@
+######################
+Description and Goals
+######################
+
+https://dmtn-227.lsst.io/
diff --git a/doc/user-guide/index.rst b/doc/user-guide/index.rst
@@ -6,3 +6,9 @@ User Guide
    :maxdepth: 1
 
    installation
+   description-and-goals
+   schemas
+   tap-clients
+   consdb-client-library-in-summit-utils
+   consdb-rest-api
+   sql-clients
diff --git a/doc/user-guide/schemas.rst b/doc/user-guide/schemas.rst
@@ -0,0 +1,13 @@
+########
+Schemas
+########
+
+* Types of schemas
+    * Summit for observers and Summit systems
+        * Smallest, contains primary key information from HeaderService and additional information from other Summit systems, including experimental and engineering data
+    * USDF for staff and analytical uses
+        * Largest, contains a full replica of the Summit plus additional information from USDF systems including Prompt Processing and Data Release Production, possibly Calibration Products Production, and human annotations from processing campaigns
+    * Release for science users
+        * Near-real-time "prompt" ConsDB replicates a subset of the USDF version
+        * Data Release ConsDB is a snapshot of a subset of the USDF version with data pertaining to the exposures/visits in the DR
+* Schema browser
diff --git a/doc/user-guide/sql-clients.rst b/doc/user-guide/sql-clients.rst
@@ -0,0 +1,8 @@
+##############################
+SQL Clients (not recommended)
+##############################
+
+* Connection information
+    * Summit
+    * USDF
+    * Release
diff --git a/doc/user-guide/tap-clients.rst b/doc/user-guide/tap-clients.rst
@@ -0,0 +1,8 @@
+############
+TAP Clients
+############
+
+* Connection information
+    * Summit
+    * USDF
+    * Release