diff --git a/doc/conf.py b/doc/conf.py index 92ef9848..1b4d3dd2 100644 --- 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 new file mode 100644 index 00000000..fa2551aa --- /dev/null +++ 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 new file mode 100644 index 00000000..271b4b50 --- /dev/null +++ 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 new file mode 100644 index 00000000..7bb1db06 --- /dev/null +++ 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 new file mode 100644 index 00000000..dc81f882 --- /dev/null +++ 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 new file mode 100644 index 00000000..7d2aba32 --- /dev/null +++ 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 new file mode 100644 index 00000000..5a56da13 --- /dev/null +++ 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 \ No newline at end of file diff --git a/doc/developer-guide/documentation.rst b/doc/developer-guide/documentation.rst new file mode 100644 index 00000000..49285ce9 --- /dev/null +++ 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 new file mode 100644 index 00000000..cbeb8451 --- /dev/null +++ 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 new file mode 100644 index 00000000..cc5768c7 --- /dev/null +++ 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 new file mode 100644 index 00000000..0aa13cfe --- /dev/null +++ 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 index 4d19b12f..eae2c8ac 100644 --- 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 new file mode 100644 index 00000000..57d530ba --- /dev/null +++ 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 new file mode 100644 index 00000000..35be85b2 --- /dev/null +++ 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 new file mode 100644 index 00000000..a7d80755 --- /dev/null +++ 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 new file mode 100644 index 00000000..c3f4a73e --- /dev/null +++ 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 new file mode 100644 index 00000000..25750dbe --- /dev/null +++ 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 new file mode 100644 index 00000000..9c28aa86 --- /dev/null +++ b/doc/user-guide/consdb-client-library-in-summit-utils.rst @@ -0,0 +1,5 @@ +###################################### +ConsDB Client Library in summit_utils +###################################### + +Querying using ConsDbClient \ No newline at end of file diff --git a/doc/user-guide/consdb-rest-api.rst b/doc/user-guide/consdb-rest-api.rst new file mode 100644 index 00000000..aa6bed9d --- /dev/null +++ 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 new file mode 100644 index 00000000..f31bb04d --- /dev/null +++ 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 index a72e2392..c3f34438 100644 --- 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 new file mode 100644 index 00000000..bc179a4e --- /dev/null +++ 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 new file mode 100644 index 00000000..13f8ea0d --- /dev/null +++ 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 new file mode 100644 index 00000000..9345715b --- /dev/null +++ b/doc/user-guide/tap-clients.rst @@ -0,0 +1,8 @@ +############ +TAP Clients +############ + +* Connection information + * Summit + * USDF + * Release