..

docs/admin/index.rst

@@ -8,7 +8,7 @@ Helm configuration
 
 The SIAv2 service is deployed via Phalanx, which requires a ``values-{env}.yaml`` configuration file to be provided. Most of the configuration is fairly standard and common with other applications in Phalanx and has defaults in the ``values.yaml``.
 
-The main configuration that needs to be provided is the Butler Repositories, and all the relevant attributes for each repository which are listed below:
+The main configuration that needs to be provided is the list of Butler Repositories (``butlerDataCollections``), and all the relevant attributes for each repository which are listed below:
 
 butlerDataCollections
 ---------------------
@@ -74,6 +74,7 @@ Vault secrets
 
 The SIA applications by default does not require any secrets to be setup by an administrator, as the secrets that it does expect are copied over from other Phalanx applications.
 An administrator can however define an environment specific secrets.yaml file and overwrite these if they wish.
+Note that the secrets currently defined in ``secrets.yaml`` are only applicable to the case that the service is supporting a Direct Butler Repository, otherwise they are not used.
 
 These secrets are listed below:
 
@@ -93,22 +94,22 @@ These secrets are listed below:
 Deployment Information
 ======================
 
-SIA will deploy one pod by default, if the config.directButlerEnabled is set to false, which is the SIA FastAPI application. This will be the relevant web-service running the SIA application. Any relevant logs during operations will be in the logs of this pod.
-If directButlerEnabled is set to true, a utility pod "fix-secret-permissions" used to setup the permissions for the Direct Butler secrets will also be spawned.
+SIA will deploy one pod by default, if the ``config.directButlerEnabled`` is set to **false**, which is the SIA FastAPI application. This will be the main FastAPI web-service running the SIA application. Any relevant logs during operations will be in the logs of this pod.
+If ``directButlerEnabled`` is set to **true**, a utility pod ``fix-secret-permissions`` used to setup the permissions for the Direct Butler secrets will also be spawned.
 
 
 Use with a Remote Butler
 ==========================
 
-To connect the SIA app with a Remote Butler repository, the values in the configuration need to be specified as described, ensuring the butler_type is set to "REMOTE". Then when a user wishes to run a query they need to provide a Bearer token as with several other apps in Phalanx (see TAP for example). This is possible with most python clients (pyvo/astropy) and is handled automatically for the user when accessing via a browser having previously logged in.
+To connect the SIA app with a Remote Butler repository, the values in the configuration need to be specified as described, ensuring their ``butler_type`` is set to **REMOTE** and that the ``config.directButlerEnabled`` field is set to **false**. Then when a user wishes to run a query they need to provide a Bearer token as with several other apps in Phalanx (see TAP for example). This is possible with most python clients (pyvo/astropy) and is handled automatically for the user when accessing via a browser having previously logged in.
 If a token is not provided the app will reject the request with an authorization error.
 
 
 Use with a Direct Butler
 ==========================
 
-If an operator of the SIA application wishes to use the app with Direct Butler access rather than remote, they can specify the above parameters making sure to set butler_type to "DIRECT" & also setting config.directButlerEnabled to true.
-When this is used the app no longer expects to read in a user token from the headers to use when setting up the Butler access, and instead uses the authentication credentials from the sia secrets to authenticate with the Butler Postgres database.
+If an operator of the SIA application wishes to use the app with Direct Butler access rather than remote, they can specify the above parameters making sure to set ``butler_type`` to **DIRECT** & also setting ``config.directButlerEnabled`` to **true**.
+When this is used the app no longer expects to read in a user token from the headers to use when setting up the Butler access, and instead uses the authentication credentials from the ``sia`` secrets to authenticate with the Butler Postgres database.
 
 
 Service Self-Description

docs/index.rst

@@ -10,14 +10,13 @@
 SIA
 ###########
 SIA is an implementation of the IVOA `Simple Image Access v2`_ protocol as a `FastAPI`_ web service, designed to be deployed as part of the Rubin Science Platform through `Phalanx`_.
+It provides a capability of discovering, retrieving and gathering metadata for image holdings, via the use of the ObsCore Data Model.
+Users will in most cases be accessing the service via other client tools like **Firefly** or **TopCat** which abstract the data access flow behind user-friendly interfaces.
 
-The default configuration uses the `dax_obscore`_ package and interacts with a `Butler`_ repository to find images matching specific criteria.
-
-While the current release supports both remote and direct (local) Butler repositories, our primary focus has been on the Remote Butler use-case, resulting in more mature support for this option.
-
+The default configuration uses the `dax_obscore`_ package and interacts with a `Butler`_ repository to find images matching specific criteria. While the current release supports both remote and direct (local) Butler repositories, our primary focus has been on the Remote Butler use-case, resulting in more mature support for this option.
 The application expects as part of the configuration a list of Butler Data Collections, each of which expects a number of attributes which define how to access the repository.
 
-SIA is developed on `SIA`_. It is deployed via Phalanx.
+The github repository for `SIA`_ is where the application is developed. See the `CHANGELOG`_ for a list of versions and changes to the application.
 
 The system architecture & design considerations have been documented in https://github.com/lsst-sqre/sqr-095.
 
@@ -41,3 +40,4 @@ The system architecture & design considerations have been documented in https://
 .. _dax_obscore: https://github.com/lsst-dm/dax_obscore
 .. _Butler: https://github.com/lsst/daf_butler
 .. _SIA: https://github.com/lsst-sqre/sia
+.. _CHANGELOG: https://github.com/lsst-sqre/sia/blob/main/CHANGELOG.md

docs/usage/index.rst

@@ -3,7 +3,7 @@ Usage
 #####
 
 
-``sia`` is an image-access API complying with the IVOA SIA (v2) specification.
+``sia`` is an image-access API implemented as a FastAPI application, deveoped using the `Safir`_ templating toolkit.
 For documentation on the protocol and details on usage including input parameters & output see the IVOA `SIAv2`_ specification.
 
 Parameters
@@ -22,11 +22,11 @@ HTTP Methods
 =============
 Both POST & GET methods are implemented for the /query API in accordance to the specification
 
-HTTP GET Example::
+HTTP **GET** Example::
 
     https://data-dev.lsst.cloud/api/sia/dp02/query?POS=CIRCLE+55.7467+-32.2862+0.05
 
-HTTP POST Example::
+HTTP **POST** Example::
 
     curl -X POST "https://data-dev.lsst.cloud/api/sia/dp02/query" \
 	-H "Authorization: Bearer your_token_here" \
@@ -127,3 +127,4 @@ the response::
 .. _Butler: https://github.com/lsst/daf_butler
 .. _pyvo: https://pyvo.readthedocs.io/en/latest/
 .. _SIAv2: https://www.ivoa.net/documents/SIA/
+.. _Safir: https://safir.lsst.io/