From e2ed339262892acdf68fd0646e5c3089debf5a93 Mon Sep 17 00:00:00 2001 From: Stelios Voutsinas Date: Tue, 8 Oct 2024 16:42:52 -0700 Subject: [PATCH] Add relevant docs config and content --- docs/_static/openapi.json | 826 ++++++++++++++++++++++++++++++++++++++ docs/conf.py | 1 + docs/documenteer.toml | 8 + docs/index.rst | 22 + 4 files changed, 857 insertions(+) create mode 100644 docs/_static/openapi.json create mode 100644 docs/conf.py create mode 100644 docs/documenteer.toml create mode 100644 docs/index.rst diff --git a/docs/_static/openapi.json b/docs/_static/openapi.json new file mode 100644 index 0000000..912f788 --- /dev/null +++ b/docs/_static/openapi.json @@ -0,0 +1,826 @@ +{ +"openapi": "3.1.0", +"info": { +"title": "sia", +"description": "Rubin Observatory SIA implementation over Butler", +"version": "0.1.dev14+gbadfd51" +}, +"paths": { +"/api/sia/": { +"get": { +"summary": "Application metadata", +"description": "Document the top-level API here. By default it only returns metadata about the application.", +"operationId": "get_index_api_sia__get", +"responses": { +"200": { +"description": "Successful Response", +"content": { +"application/json": { +"schema": { +"$ref": "#/components/schemas/Index" +} +} +} +} +} +} +}, +"/api/sia/availability": { +"get": { +"summary": "IVOA service availability", +"description": "VOSI-availability resource for the service", +"operationId": "get_availability_api_sia_availability_get", +"responses": { +"200": { +"description": "Successful Response", +"content": { +"application/json": { +"schema": {} +}, +"application/xml": {} +} +} +} +} +}, +"/api/sia/capabilities": { +"get": { +"summary": "IVOA service capabilities", +"description": "VOSI-capabilities resource for the SIA service.", +"operationId": "get_capabilities_api_sia_capabilities_get", +"responses": { +"200": { +"description": "Successful Response", +"content": { +"application/json": { +"schema": {} +}, +"application/xml": {} +} +} +} +} +}, +"/api/sia/query": { +"get": { +"summary": "IVOA SIA service query", +"description": "Query endpoint for the SIA service.", +"operationId": "query_get_api_sia_query_get", +"parameters": [ +{ +"name": "pos", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "pos", +"description": "Positional region(s) to be searched", +"examples": [ +"320 -0.1 10" +] +}, +"description": "Positional region(s) to be searched" +}, +{ +"name": "format", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "format", +"description": "Response format(s)", +"examples": [ +"application/x-votable+xml" +] +}, +"description": "Response format(s)" +}, +{ +"name": "time", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "time", +"description": "Time interval(s) to be searched", +"examples": [ +"2021-01-01T00:00:00Z 2021-01-02T00:00:00Z" +] +}, +"description": "Time interval(s) to be searched" +}, +{ +"name": "band", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "band", +"description": "Energy interval(s) to be searched", +"examples": [ +"0.1 10.0" +] +}, +"description": "Energy interval(s) to be searched" +}, +{ +"name": "pol", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"$ref": "#/components/schemas/Polarization" +} +}, +{ +"type": "null" +} +], +"title": "pol", +"description": "Polarization state(s) to be searched", +"examples": [ +"I", +"Q" +] +}, +"description": "Polarization state(s) to be searched" +}, +{ +"name": "fov", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "fov", +"description": "Range(s) of field of view", +"examples": [ +"1.0 2.0" +] +}, +"description": "Range(s) of field of view" +}, +{ +"name": "spatres", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "spatres", +"description": "Range(s) of spatial resolution", +"examples": [ +"0.1 0.2" +] +}, +"description": "Range(s) of spatial resolution" +}, +{ +"name": "exptime", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "exptime", +"description": "Range(s) of exposure times", +"examples": [ +"-Inf 60" +] +}, +"description": "Range(s) of exposure times" +}, +{ +"name": "timeres", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "timeres", +"description": "Range(s) of temporal resolution", +"examples": [ +"-Inf 1.0" +] +}, +"description": "Range(s) of temporal resolution" +}, +{ +"name": "specrp", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "specrp", +"description": "Range(s) of spectral resolving power", +"examples": [ +"1000 2000" +] +}, +"description": "Range(s) of spectral resolving power" +}, +{ +"name": "id", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "id", +"description": "Identifier of dataset(s)", +"examples": [ +"obs_id_1" +] +}, +"description": "Identifier of dataset(s)" +}, +{ +"name": "dptype", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"$ref": "#/components/schemas/DPType" +} +}, +{ +"type": "null" +} +], +"title": "dptype", +"description": "Type of data", +"examples": [ +"image" +] +}, +"description": "Type of data" +}, +{ +"name": "calib", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"$ref": "#/components/schemas/CalibLevel" +} +}, +{ +"type": "null" +} +], +"title": "calib", +"description": "Calibration level of the data", +"examples": [ +0, +1, +2 +] +}, +"description": "Calibration level of the data" +}, +{ +"name": "target", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "target", +"description": "Name of the target", +"examples": [ +"M31" +] +}, +"description": "Name of the target" +}, +{ +"name": "collection", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "collection", +"description": "Name of the data collection", +"examples": [ +"HST" +] +}, +"description": "Name of the data collection" +}, +{ +"name": "facility", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "facility", +"description": "Name of the facility", +"examples": [ +"HST" +] +}, +"description": "Name of the facility" +}, +{ +"name": "instrument", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "array", +"items": { +"type": "string" +} +}, +{ +"type": "null" +} +], +"title": "instrument", +"description": "Name of the instrument", +"examples": [ +"ACS" +] +}, +"description": "Name of the instrument" +}, +{ +"name": "maxrec", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "integer" +}, +{ +"type": "null" +} +], +"title": "maxrec", +"description": "Maximum number of records in the response", +"examples": [ +10 +] +}, +"description": "Maximum number of records in the response" +}, +{ +"name": "responseformat", +"in": "query", +"required": false, +"schema": { +"anyOf": [ +{ +"type": "string" +}, +{ +"type": "null" +} +], +"title": "reponseformat", +"description": "Format of the response", +"examples": [ +"application/x-votable+xml" +] +}, +"description": "Format of the response" +} +], +"responses": { +"200": { +"description": "Successful Response", +"content": { +"application/json": { +"schema": {} +}, +"application/xml": {} +} +}, +"400": { +"description": "Invalid query parameters", +"content": { +"application/json": { +"schema": { +"$ref": "#/components/schemas/ErrorModel" +} +} +} +}, +"422": { +"description": "Validation Error", +"content": { +"application/json": { +"schema": { +"$ref": "#/components/schemas/HTTPValidationError" +} +} +} +} +} +}, +"post": { +"summary": "IVOA SIA (v2) service query (POST)", +"description": "Query endpoint for the SIA service (POST method).", +"operationId": "query_post_api_sia_query_post", +"responses": { +"200": { +"description": "Successful Response", +"content": { +"application/json": { +"schema": {} +}, +"application/xml": {} +} +}, +"400": { +"description": "Invalid query parameters", +"content": { +"application/json": { +"schema": { +"$ref": "#/components/schemas/ErrorModel" +} +} +} +}, +"422": { +"description": "Validation Error", +"content": { +"application/json": { +"schema": { +"$ref": "#/components/schemas/HTTPValidationError" +} +} +} +} +} +} +} +}, +"components": { +"schemas": { +"CalibLevel": { +"type": "integer", +"enum": [ +0, +1, +2, +3 +], +"title": "CalibLevel", +"description": "Enumeration of possible calibration levels." +}, +"DPType": { +"type": "string", +"enum": [ +"IMAGE", +"CUBE" +], +"title": "DPType", +"description": "Enumeration of possible data product types." +}, +"ErrorDetail": { +"properties": { +"loc": { +"anyOf": [ +{ +"items": { +"type": "string" +}, +"type": "array" +}, +{ +"type": "null" +} +], +"title": "Location", +"examples": [ +[ +"area", +"field" +] +] +}, +"msg": { +"type": "string", +"title": "Message", +"examples": [ +"Some error messge" +] +}, +"type": { +"type": "string", +"title": "Error type", +"examples": [ +"some_code" +] +} +}, +"type": "object", +"required": [ +"msg", +"type" +], +"title": "ErrorDetail", +"description": "The detail of the error message." +}, +"ErrorModel": { +"properties": { +"detail": { +"items": { +"$ref": "#/components/schemas/ErrorDetail" +}, +"type": "array", +"title": "Detail" +} +}, +"type": "object", +"required": [ +"detail" +], +"title": "ErrorModel", +"description": "A structured API error message." +}, +"HTTPValidationError": { +"properties": { +"detail": { +"items": { +"$ref": "#/components/schemas/ValidationError" +}, +"type": "array", +"title": "Detail" +} +}, +"type": "object", +"title": "HTTPValidationError" +}, +"Index": { +"properties": { +"metadata": { +"$ref": "#/components/schemas/Metadata", +"title": "Package metadata" +} +}, +"type": "object", +"required": [ +"metadata" +], +"title": "Index", +"description": "Metadata returned by the external root URL of the application.\n\nNotes\n-----\nAs written, this is not very useful. Add additional metadata that will be\nhelpful for a user exploring the application, or replace this model with\nsome other model that makes more sense to return from the application API\nroot." +}, +"Metadata": { +"properties": { +"name": { +"type": "string", +"title": "Application name", +"examples": [ +"myapp" +] +}, +"version": { +"type": "string", +"title": "Version", +"examples": [ +"1.0.0" +] +}, +"description": { +"anyOf": [ +{ +"type": "string" +}, +{ +"type": "null" +} +], +"title": "Description", +"examples": [ +"Some package description" +] +}, +"repository_url": { +"anyOf": [ +{ +"type": "string" +}, +{ +"type": "null" +} +], +"title": "Repository URL", +"examples": [ +"https://example.com/" +] +}, +"documentation_url": { +"anyOf": [ +{ +"type": "string" +}, +{ +"type": "null" +} +], +"title": "Documentation URL", +"examples": [ +"https://example.com/" +] +} +}, +"type": "object", +"required": [ +"name", +"version" +], +"title": "Metadata", +"description": "Metadata about a package." +}, +"Polarization": { +"type": "string", +"enum": [ +"I", +"Q", +"U", +"V", +"RR", +"LL", +"RL", +"LR", +"XX", +"YY", +"XY", +"YX" +], +"title": "Polarization", +"description": "Enumeration of possible polarization states." +}, +"ValidationError": { +"properties": { +"loc": { +"items": { +"anyOf": [ +{ +"type": "string" +}, +{ +"type": "integer" +} +] +}, +"type": "array", +"title": "Location" +}, +"msg": { +"type": "string", +"title": "Message" +}, +"type": { +"type": "string", +"title": "Error Type" +} +}, +"type": "object", +"required": [ +"loc", +"msg", +"type" +], +"title": "ValidationError" +} +} +} +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3fd6377 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1 @@ +from documenteer.conf.guide import * diff --git a/docs/documenteer.toml b/docs/documenteer.toml new file mode 100644 index 0000000..a70b400 --- /dev/null +++ b/docs/documenteer.toml @@ -0,0 +1,8 @@ +[project] +title = "SIA" +copyright = "2024 Association of Universities for Research in Astronomy, Inc. (AURA)" +base_url="https://sia.lsst.io" +github_url="https://github.com/lsst-sqre/sia" + +[project.python] +package = "sia" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..567f550 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +.. toctree:: + :maxdepth: 1 + :hidden: + +########### +SIA +########### + + +SIA is an implementation of the IVOA [Simple Image Access v2](https://www.ivoa.net/documents/SIA/20150610/PR-SIA-2.0-20150610.pdf) protocol as a [FastAPI](https://fastapi.tiangolo.com/) web service, designed to be deployed as part of the Rubin Science Platform. + +The default configuration is designed to use the [dax_obscore](https://github.com/lsst-dm/dax_obscore) package and interact with a [Butler](https://github.com/lsst/daf_butler) repository to find images that match a certain criteria. +While the application has been designed with consideration to potential future use with other middleware packages & query engines, the current release is targeted to the specific Butler-backed use case for the RSP. +Queries results are streamed as VOTable responses to the user, and in the current release this is the only format supported. +The application expects as configuration the definition of what query_engine to use, and the associated data collections configuration. In the default case of using Remote Butler as the query engine, the application expects at least one data collection (with default=True). + + +The system architecture & design considerations have been documented in https://github.com/lsst-sqre/sqr-095. + +See [CHANGELOG.md](https://github.com/lsst-sqre/sia/blob/main/CHANGELOG.md) for the change history of sia. + +