Create TimeSeries documentation for Read the Docs

[krowvin]

Requesting initial documentation page for Time Series on Read the Docs

https://cwms-data-api.readthedocs.io/latest/

Suggestions:

• Avoid repeating what is already in the swagger docs OR schema docs in the read the docs, instead expand on what is there with more detail.
  i.e. "Retrieves a TimeSeries Group" does not explain what a TS group is
• Audience should be end users, the public, stakeholder, water management, and other focused. Not developer (swagger is more for dev docs)

  • Could cater to both audiences (dev and non dev), but start with the above general audiences in mind

  • Do not use jargon like

    • "HTTP GET request response from the timeseries endpoint is a 2d array consisting of..."

    instead use

    • "Reading data from timeseries consists of a list of timeseries values. Each value contains 3 (4?) distinct values of datetime (link to this), value (link to this), and quality (link to this doc)...etc"

• Make sure to consistently type TimeSeries or Time Series and not Timeseries
• Explain where possible what something is, without tying it to any context like a "GET". For example, when describing a location level, you can explain what that is and what sort of data it might return. But the context of what endpoints it belongs to can be determined from the swagger page.
• Where prevalent for understanding, do NOT repeat what is already listed in the CWMS schema. Instead (possibly) link to a public version of the CWMS Schema docs -
  i.e. Publish the Schema Documentation HydrologicEngineeringCenter/cwms-database#17
• Define something generic like office in one place. Then reference that place in the docs on the various endpoint names. Do not repeat the same definition of office in each place of the docs. This lends to variations like this:

Tasks

1. TimeSeries Landing Page that defines what a TimeSeries is, and what sort of data you might find
2. Explain the various parts of a timeseries: i.e. Location.Parmater.Type.Interval.Version
   a. If you can, break off into sections for what each of these are and add reference holders to where they are mentioned elsewhere (other endpoints)
   b. Create a doc for alternative topics like "Aliases" which would be useful for timeseries aliases and location aliases. (Or link to schema docs)
3. Endpoints - Break off into sub sections for each endpoint type. GET, POST, DELETE, PATCH
   a. GET - Group up the various endpoints for read access. (Screenshot )
   A grouping of endpoints might have an index of the various names:
   • /timeseries/profile (etc)
     • Details: What is a profile used for? What is a profile? When might you use this? What does it mean to have a profile of timeseries? etc
     • Params: Then within profile list out what each param means:
       • For example, each of the endpoints has params. A user will not know what "location-id" means, or what a valid value is. This changes per endpoint sometimes. Add general reference to shared points. I.e. "KEYS" and link to the doc about locations on the "timeseries location part" above (2 above)
   • And so on for the other GET methods (recent, profile-parser, profile-instance, / )
     b. POST, DELETE, UPDATE - Should have similar fields and explanations as the above, linking to the shared pages for resources. They should also contain links to a "authentication" doc (for now link to coming soon page) Focus only on GET for now, majority of entities in audience will only care for reading data and what/who/when/where/whys/hows of the endpoints.
4. Create a "Coming Soon" page - for all link references that cannot be filed now, add a place holder to a "coming soon" page. From this page you could add a link to the GitHub issues page for additional page requests.
5. On each page and/or the footer add a button to "correct docs". This should allow users to submit an issue to github regarding the doc. (TODO: setup issue templates for "issue from docs", etc)

Other:

• In each endpoint on Swagger UI, where needed, add a link to the relevant Read the Docs article
• Supplement documentation on swagger (separate PR) for placeholders using example values instead of
  Name: Name - specifies the name... Per Use Test Examples as the placeholder for SwaggerUI? #930

Endpoints to Cover in this Issue:

Relevant Links:

Discussion - #1116

[rma-kayla]

@krowvin
Charles, in regard to your comment above in the Suggestions section:
"Where prevalent for understanding, do NOT repeat what is already listed in the CWMS schema. Instead (possibly) link to a public version of the CWMS Schema docs -
i.e. HydrologicEngineeringCenter/cwms-database#17"

I followed the directions on issue 17 to download the cwms-database-schema-25-07-01-RC06-docs file and reviewed the index.html page.

• How do we access the most current production version of the cwms schema for linking this time series documentation to the CWMS schema docs?
• Is this hosted/published somewhere publicly that we can link to?

@MikeNeilson @rma-psmorris @rripken

[MikeNeilson]

https://cwms-database.readthedocs.io/en/latest/

[MikeNeilson]

As far as "production vs latest dev", still sorting that out, but that will be the location.