small doc improvements from user testing

documentation/api/introduction.rst

@@ -257,7 +257,9 @@ In case of a single group of connections, the message may be flattened to:
 Timeseries
 ^^^^^^^^^^
 
-Timestamps and durations are consistent with the ISO 8601 standard. All timestamps in requests to the API must be timezone-aware. The timezone indication "Z" indicates a zero offset from UTC. Additionally, we use the following shorthand for sequential values within a time interval:
+Timestamps and durations are consistent with the ISO 8601 standard. The resolution of the data is implicit, see :ref:`resolutions`.
+
+All timestamps in requests to the API must be timezone-aware. The timezone indication "Z" indicates a zero offset from UTC. Additionally, we use the following shorthand for sequential values within a time interval:
 
 .. code-block:: json
 
@@ -405,8 +407,9 @@ This denotes that the prognosed interval has 5 minutes left to be concluded.
 Resolutions
 ^^^^^^^^^^^
 
-Specifying a resolution is redundant for POST requests that contain both "values" and a "duration".
-Also, posted data is checked against the required resolution of the assets which are posted to.
+Specifying a resolution is redundant for POST requests that contain both "values" and a "duration" ― FlexMeasures computes the resolution by dividing the duration by the number of values.
+
+When POSTing data, FlexMeasures checks this computed resolution against the required resolution of the assets which are posted to. If these can't be matched (through upsampling), an error will occur.
 
 GET requests (such as *getMeterData*) return data in the resolution which the sensor is configured for.
 A "resolution" may be specified explicitly to obtain the data in downsampled form, 

documentation/dev/data.rst

@@ -100,36 +100,35 @@ Or, from within Postgres console:
    CREATE DATABASE flexmeasures_test WITH OWNER = flexmeasures_test;
 
 
-Log in as the postgres superuser and connect to your newly-created database:
+Finally, test if you can log in as the flexmeasures user:
 
 .. code-block:: bash
 
-   sudo -u postgres psql
+   psql -U flexmeasures --password -h 127.0.0.1 -d flexmeasures
 
 .. code-block:: sql
 
-   \connect flexmeasures
+   \q
+
 
+Add Postgres Extensions to your database(s)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+To find the nearest sensors, FlexMeasures needs some extra POstgres support. 
 Add the following extensions while logged in as the postgres superuser:
 
+.. code-block:: bash
+
+   sudo -u postgres psql
+
 .. code-block:: sql
 
+   \connect flexmeasures
    CREATE EXTENSION cube;
    CREATE EXTENSION earthdistance;
 
 
-Connect to the ``flexmeasures_test`` database and repeat creating these extensions there. Then ``exit``.
-
-Finally, try logging in as the flexmeasures user once:
-
-.. code-block:: bash
-
-   psql -U flexmeasures --password -h 127.0.0.1 -d flexmeasures
-
-.. code-block:: sql
-
-   \q
+If you have it, connect to the ``flexmeasures_test`` database and repeat creating these extensions there. Then ``exit``.
 
 
 Configure FlexMeasures app for that database

documentation/getting-started.rst

@@ -17,6 +17,7 @@ Install dependencies and the ``flexmeasures`` platform itself:
 
    pip install flexmeasures
 
+.. note:: With newer Python versions and Windows, some smaller dependencies (e.g. ``tables`` or ``rq-win``) might cause issues as support is often slower. You might overcome this with a little research, by `installing from wheels <http://www.pytables.org/usersguide/installation.html#prerequisitesbininst>`_ or `from the repo <https://github.com/michaelbrooks/rq-win#installation-and-use>`_, respectively.
 
 
 Make a secret key for sessions and password salts
@@ -217,7 +218,7 @@ To collect weather measurements and forecasts from the DarkSky API, there is a t
 
    flexmeasures add external-weather-forecasts --location 33.4366,126.5269 --store-in-db 
 
-.. note::  DarkSky is not handing out tokens anymore, as they have been bought by Apple (see `issue 3 <https://github.com/SeitaBV/flexmeasures/issues/56>`_).
+.. note::  DarkSky is not handing out tokens any more, as they have been bought by Apple (see `issue 3 <https://github.com/SeitaBV/flexmeasures/issues/56>`_).
 
 
 Preparing the job queue database and start workers

flexmeasures/api/common/responses.py

@@ -86,7 +86,7 @@ def invalid_ptu_duration(message: str) -> ResponseTuple:
     )
 
 
-@BaseMessage("Only the following resolutions are supported:")
+@BaseMessage("Only the following resolutions in the data are supported:")
 def unapplicable_resolution(message: str) -> ResponseTuple:
     return dict(result="Rejected", status="INVALID_RESOLUTION", message=message), 400
 

flexmeasures/data/scripts/cli_tasks/data_add.py

@@ -230,14 +230,14 @@ def add_initial_structure():
     multiple=True,
     type=click.Choice(["1", "6", "24", "48"]),
     default=["1", "6", "24", "48"],
-    help="Forecasting horizon in hours. This argument can be given multiple times.",
+    help="Forecasting horizon in hours. This argument can be given multiple times. Defaults to all possible horizons.",
 )
 @click.option(
     "--as-job",
     is_flag=True,
     help="Whether to queue a forecasting job instead of computing directly."
     " Useful to run locally and create forecasts on a remote server. In that case, just point the redis db in your"
-    " config settings to that of the remote server. To process the job, run a worker to process the forecasting queue.",
+    " config settings to that of the remote server. To process the job, run a worker to process the forecasting queue. Defaults to False.",
 )
 def create_forecasts(
     asset_type: str = None,