Documentation Publication

[mike-gangl]

Documentation Publication

All APIs, libraries, and user facing functions that we own must be documented and published. This does not include COTS products like Jupyter, Airflow, etc, though we may want to ensure existing documentation for that is valid.

Acceptance Criteria

Acceptance criteria required to implement the epic

• Unity-sds-client documentation is published and up to date with latest capabilities
• All Schemas are documneted as openAPI specifications and are CMed in https://github.com/unity-sds/unity-monorepo/tree/main/schemas
• All Schemas are published - see https://github.com/unity-sds/unity-monorepo/tree/main/schemas/app-package-service and https://github.com/unity-sds/unity-monorepo/blob/main/.github/workflows/schema_apgs.yml for examples of publishing and documenting a schema automatically
• Schemas we expect:
  • OGC server api (SPS)
  • DAPA server API (UDS)
  • App-package-generation-system (ADS)
  • Healthcheck schema (CS?)
  • Others?
• Librariers we expect:
  • unity-sds-client (UIUX)
  • uds-stage-in/out libraries (UDS)
• Other Documentation
• Stage-in/Stage-out documentation - required parameters for stage_out, automated cataloging, and the STAC requirements (e.g. must include the stac.json)
• Documentation should be linked from gitbook where applicable.

Work Tickets

Link to work tickets required to implement the epic

• TBC (to be created)

Dependencies

Other epics or outside tickets required for this to work

• TBC

Associated Risks

links to risk issues associated with this epic

• TBC

[mike-gangl]

See #205 for some specific doc issues

[brianlee731]

For U-DS:
Stage-In/Stage-Out Overview: Provide an overview of the Stage-In/Stage-Out processes, including the STAC format/specification, and explain how they integrate within the overall framework.

Examples: Offer multiple examples demonstrating the Stage-In/Stage-Out processes in various scenarios, with step-by-step procedures and accompanying screenshots or diagrams where applicable.

Best Practices: Document best practices for effectively using Stage-In/Stage-Out and highlight common user confusions or mistakes.

For U-SPS:
Overview of OGC Processing: Provide an overview of the OGC processing, including the OGC standard/specification.

Best Practices: Document best practices for using the Airflow OGC API and DAG effectively, and highlight common user confusions or mistakes. (future) Consider including best practices for writing DAGs for capturing airflow processing metrics.

Examples: Offer multiple examples demonstrating the OGC processing in various scenarios, with step-by-step procedures and accompanying screenshots or diagrams where applicable. Reference the existing OGC API notebook. (Drew already put together notebooks and request ASIPS review for what's missing)

For U-ADS:
Overview of OGC Application Package Process: Provide an overview of the OGC application package, including the CWL format/specification.

Best Practices: Document best practices for using/writing CWL, assuming users do not utilize the app-pack-gen and without JupyterHub, and highlight common user confusions or mistakes.

Examples: Offer multiple examples demonstrating the OGC processing in various scenarios, with step-by-step procedures and accompanying screenshots or diagrams where applicable. Note that a user guide currently exists in GitBook but needs more examples tailored towards CWL without using JuyterHub and app-pack-gen.

Given a Docker container, how would you put together CWL to run it (stage-in/stage-out/process/workflow)

For U-CS:
Overview of Infrastructure, Marketplace, and Management Console: Provide an overview of the infrastructure and the services managed by U-CS, including an overview of the marketplace and management console, with a step-by-step outline.

For U-UX:
Overview of MDPS/Unity Dashboard: Provide an overview of the common user interface and the health dashboard.

PSE:
Document the process for the team
Examples: Offer multiple examples demonstrating use of unity-sds-client libraries

[rtapella]

Honestly if we need documentation to use the dashboard then we're hosed :D

I do think we need to keep updating the end-to-end tutorials/docs

[brianlee731]

@rtapella The documentation for the dashboard would be an overview that we include in the gitbook. I did not look through it in detail, but I didn't find a page in the gitbook that references the dashboard.

[LucaCinquini]

The following documentation has been reviewed and updated for SPS:

https://unity-sds.gitbook.io/docs/developer-docs/science-processing/docs/developers-guide

https://unity-sds.gitbook.io/docs/developer-docs/science-processing/docs/developers-guide/ogc-processes-api-overview

https://unity-sds.gitbook.io/docs/developer-docs/science-processing/docs/developers-guide/tutorial-using-the-ogc-processes-api-with-curl

https://unity-sds.gitbook.io/docs/developer-docs/science-processing/docs/developers-guide/tutorial-using-the-ogc-processes-api-with-python
(this last one references an updated version of the OGC Processes Jupyter Notebook).