From 28b389696672d0866e7b3a208752cd352efb1c58 Mon Sep 17 00:00:00 2001 From: cairosanders Date: Tue, 22 Sep 2020 17:11:57 -0700 Subject: [PATCH 1/2] use m2r2 instead of m2r --- doc/source/conf.py | 2 +- requirements.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index b6953c91..b5fe4bf3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,7 +33,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "m2r"] +extensions = ["sphinx.ext.autodoc", "m2r2"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/requirements.txt b/requirements.txt index efa56774..c6f5ed55 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,5 +11,5 @@ sqlalchemy==1.3.17 contexttimer==0.3.3 # For documentation -Sphinx==2.4.4 -m2r==0.2.1 +Sphinx==3.2.1 +m2r2==0.2.5 From 0fe49712a92ca3b45084c15b82bd24b25217a16c Mon Sep 17 00:00:00 2001 From: cairosanders Date: Thu, 24 Sep 2020 09:46:52 -0700 Subject: [PATCH 2/2] Fix formatting in md files --- doc/source/api/api-overview.md | 2 +- doc/source/workflow.md | 26 ++++++++++++-------------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/doc/source/api/api-overview.md b/doc/source/api/api-overview.md index da4f6e6c..9e4a9e3f 100644 --- a/doc/source/api/api-overview.md +++ b/doc/source/api/api-overview.md @@ -1,6 +1,6 @@ Documentation for each API endpoint is automatically generated from the code and docstring for that API's main function and may not be entirely user-friendly. There are some minor differences between the internal workings of the API function and the process of querying them over the web. -The query URL is constructed from a base url ending in a slash, followed by the name of the endpoint, a question mark, and then one or more parameters of the form `attribute=value', seperated by ampersands. Parameters supplied via query URL should be web-encoded so that they will be correctly parsed. +The query URL is constructed from a base url ending in a slash, followed by the name of the endpoint, a question mark, and then one or more parameters of the form `attribute=value`, seperated by ampersands. Parameters supplied via query URL should be web-encoded so that they will be correctly parsed. The automatically generated API documentation describes a `sesh` (database session) argument to each API function. Database sessions are supplied by the query parser and does not need to be given in the query URL. diff --git a/doc/source/workflow.md b/doc/source/workflow.md index 3f950a03..e0cd6ffb 100644 --- a/doc/source/workflow.md +++ b/doc/source/workflow.md @@ -19,8 +19,8 @@ aggregates. Each individual value in these files represents a mean or stanard deviation calculated across multiple years, typically thirty years, which is standard in climate science. For example, a monthly climatological mean might cover 1961-1990, but feature only twelve timestamps. The January timestamp is -the mean of the value for January 1961, January 1962, and so on up to January -1990. The February timestamp is the mean of the values for February 1961, +the mean of the value for January 1961, January 1962, and so on up to January 1990. The February timestamp is the mean of the values for +February 1961, February 1962, and so on. Climatological means may be monthly, seasonal, or annual. This API primarily supports analysis of climatological datasets, and more analysis options are available for them. @@ -79,23 +79,21 @@ ensemble named `bc_moti`, with variable name equal to `streamflow`. When requesting streamflow data from a point, please be cautious and aware of potential differences in precision. Note that while you may supply a point - with arbitrarily precise longitude and latitude values to the API, the - streamflow data is a gridded dataset and has only one value available per - grid cell. If you supply the coordinates of a small creek inside the same - grid cell as a river, the data you receive is for the total flow through - that grid cell; it is primarily influenced by the river. Accordingly, - this dataset is more accurate for larger streams, and should not be - considered accurate for streams that drain watersheds of less than 200 - kilometers area. Information on the grid corresponding to a dataset can - be obtained from the `grid` API, which will provide a list of the longitudes - and latitudes corresponding to the centroids of each grid cell. +with arbitrarily precise longitude and latitude values to the API, the +streamflow data is a gridded dataset and has only one value available per +grid cell. If you supply the coordinates of a small creek inside the same +grid cell as a river, the data you receive is for the total flow through +that grid cell; it is primarily influenced by the river. Accordingly, +this dataset is more accurate for larger streams, and should not be +considered accurate for streams that drain watersheds of less than 200 +kilometers area. Information on the grid corresponding to a dataset can +be obtained from the `grid` API, which will provide a list of the longitudes and latitudes corresponding to the centroids of each grid cell. To get contextual information on the watershed that drains to the streamflow location of interest, the `watershed` API can be invoked with the same WKT Point used to request streamflow data. This API provides information on the topology and extent of the watershed that drains to the grid cell -containing the specified point. The outline of the watershed is provided as a -GeoJSON object. This outline, like the streamflow data itself, has a +containing the specified point. The outline of the watershed is provided as a GeoJSON object. This outline, like the streamflow data itself, has a resolution determined by the size of a grid cell. The GeoJSON watershed polygon can furthermore be used to request data on