Update docs.

smithara · smithara · commit 5fc0d9d6e044 · 2019-09-11T18:05:49.000+01:00
diff --git a/README.rst b/README.rst
@@ -9,6 +9,10 @@ viresclient
     :target: http://viresclient.readthedocs.io/
     :alt: Documentation Status
 
+.. image:: https://requires.io/github/ESA-VirES/VirES-Python-Client/requirements.svg?branch=master
+    :target: https://requires.io/github/ESA-VirES/VirES-Python-Client/requirements/?branch=master
+    :alt: Requirements Status
+
 .. image:: https://travis-ci.org/ESA-VirES/VirES-Python-Client.svg?branch=master
     :target: https://travis-ci.org/ESA-VirES/VirES-Python-Client
 
diff --git a/docs/api.rst b/docs/api.rst
@@ -32,6 +32,10 @@ ClientConfig
     :show-inheritance:
     :inherited-members:
 
+set_token
+=========
+
+.. autofunction:: viresclient.set_token
 
 DataUpload
 ==========
diff --git a/docs/available_parameters.rst b/docs/available_parameters.rst
@@ -12,6 +12,12 @@ You can check which parameters are available with:
   req.available_models()
   req.available_auxiliaries()
 
+The available measurements are segregated according to the "collection" (essentially Swarm products): each ``collection`` has a number of ``measurements`` associated with it, and the appropriate collection must be set in order to access the measurements. ``auxiliaries`` are available together with any set ``collection``. ``models`` provide magnetic model evaluation on demand, at the locations of the time series which is being accessed.
+
+See the `Swarm Data Handbook`_ for details about the products.
+
+.. _`Swarm Data Handbook`: https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/
+
 ----
 
 ``collections``
@@ -71,22 +77,41 @@ For IPD::
 ``models``
 ----------
 
-Models are evaluated along the satellite track at the positions of the measurements.
+Models are evaluated along the satellite track at the positions of the time series that has been requested. These must be used together with one of the MAG collections, and one or both of the "F" and "B_NEC" measurements. This can yield either the model values together with the measurements, or the data-model residuals.
 
 ::
 
-  IGRF12, SIFM, CHAOS-6-Combined, CHAOS-6-Core, CHAOS-6-Static,
-  MCO_SHA_2C, MCO_SHA_2D, MCO_SHA_2F, MLI_SHA_2C, MLI_SHA_2D,
-  MMA_SHA_2C-Primary, MMA_SHA_2C-Secondary,
-  MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
-  MIO_SHA_2C-Primary, MIO_SHA_2C-Secondary,
+  IGRF12,
+
+  # Comprehensive inversion (CI) models:
+  MCO_SHA_2C,                                # Core
+  MLI_SHA_2C,                                # Lithosphere
+  MMA_SHA_2C-Primary, MMA_SHA_2C-Secondary,  # Magnetosphere
+  MIO_SHA_2C-Primary, MIO_SHA_2C-Secondary,  # Ionosphere
+
+  # Dedicated inversion models:
+  MCO_SHA_2D,
+  MLI_SHA_2D,
   MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary
 
-(``residuals`` available when combined with MAG ``measurements`` ``F`` and/or ``B_NEC``)
+  # Fast-track models:
+  MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
+
+  # CHAOS models:
+  CHAOS-6-Core,
+  CHAOS-6-Static,
+  CHAOS-6-MMA-Primary, CHAOS-6-MMA-Secondary
+
+  # Other lithospheric models:
+  MF7, LCS-1
 
-Custom models can be provided as a .shc file and become accessible in the same way as pre-defined models, under the name ``"Custom_Model"``.
+Custom (user uploaded) models can be provided as a .shc file and become accessible in the same way as pre-defined models, under the name ``"Custom_Model"``.
+
+Flexible evaluation of models and defining new derived models is possible with the "model expressions" functionality whereby models can be defined like:
+
+.. code-block:: python
 
-Flexible evaluation of models and defining new derived models is possible with the "model expressions" functionality whereby models can be defined like ``"Combined_model = 'MMA_SHA_2F-Primary'(min_degree=1,max_degree=1) + 'MMA_SHA_2F-Secondary'(min_degree=1,max_degree=1)"``
+  "Combined_model = 'MMA_SHA_2F-Primary'(min_degree=1,max_degree=1) + 'MMA_SHA_2F-Secondary'(min_degree=1,max_degree=1)"
 
 ----
 
diff --git a/docs/config_details.rst b/docs/config_details.rst
@@ -0,0 +1,105 @@
+Configuration Details
+=====================
+
+While it is possible to enter the server URL and access credentials each time a new request object is created,
+
+.. code-block:: python
+
+  from viresclient import SwarmRequest
+
+  # both URL and access token passed as request object's parameters
+  request = SwarmRequest(
+      url="https://vires.services/ows",
+      token="r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-"
+  )
+
+it is more convenient to omit them from the code and store them in a private configuration file. This configuration can be done using the :meth:`viresclient.set_token` convenience function, the underlying :meth:`viresclient.ClientConfig` module, or the command line interface (CLI) - see below. These will all set the configuration options in a file which is by default located at ``~/.viresclient.ini`` which can be edited directly, containing for example::
+
+  [https://vires.services/ows]
+  token = r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
+
+  [default]
+  url = https://vires.services/ows
+
+When creating the configuration file manually make sure the file is readable by its owner only::
+
+    $ chmod 0600 ~/.viresclient.ini
+    $ ls -l ~/.viresclient.ini
+    -rw-------  1 owner owner  361 May 12 09:12 /home/owner/.viresclient.ini
+
+When the configuration file is present, then the url and token options can be omitted from requests:
+
+.. code-block:: python
+
+  # access token read from configuration
+  request = SwarmRequest(url="https://vires.services/ows")
+
+  # both default URL and access token read from configuration
+  request = SwarmRequest()
+
+The following sections describe how to set the configuration.
+
+
+Configuration via CLI
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``viresclient`` shell command can be used to set the server access configuration::
+
+  $ viresclient set_token https://vires.services/ows
+  Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
+
+  $ viresclient set_default_server https://vires.services/ows
+
+See also: :doc:`cli`
+
+Configuration via Python
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code to store the token in the ``viresclient`` configuration:
+
+.. code-block:: python
+
+  from viresclient import ClientConfig
+
+  cc = ClientConfig()
+  cc.set_site_config("https://vires.services/ows", token="r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-")
+  cc.default_url = "https://vires.services/ows"
+  cc.save()
+
+Alternatively, use the convenience function:
+
+.. code-block:: python
+
+  from viresclient import set_token
+  set_token("https://vires.services/ows")
+  # (you will now be prompted to enter the token)
+
+which calls the same code as above, but makes sure the token remains hidden so that it can't accidentally be shared.
+
+
+For developers & DISC users
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The accounts for the staging server (``staging.vires.services``), and DISC server (``staging.viresdisc.vires.services``) are separate. Tokens can be similarly generated on these and stored in the same configuration file alongside the others::
+
+  $ viresclient set_token https://vires.services/ows
+  Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
+
+  $ viresclient set_token https://staging.viresdisc.vires.services/ows
+  Enter access token: VymMHhWjZ-9nSVs-FuPC27ca8C6cOyij
+
+  $ viresclient set_default_server https://vires.services/ows
+
+Using ``SwarmRequest()`` without the ``url`` parameter will use the default URL set above. To access a non-default server the URL parameter must be used:
+
+.. code-block:: python
+
+  from viresclient import SwarmRequest
+
+  # request using the default server (https://vires.services/ows)
+  request = SwarmRequest()
+
+  # request to an alternative, non-default server
+  request = SwarmRequest(url="https://staging.viresdisc.vires.services/ows")
+
+The older HTTP basic access authentication (i.e. username + password) is still available on the staging servers and these credentials can also be configured using :meth:ClientConfig. However, this is not available on the production server and may be removed in the future, so should not be used.
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,6 +7,7 @@ Welcome to VirES-Python-Client's documentation!
 
   readme
   installation
+  config_details
   available_parameters
   release_notes
 
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -18,16 +18,17 @@ It can currently be installed with::
 
 Dependencies::
 
-  Jinja2 ≥ 2.10.0
-  tables ≥ 3.4.4
-  tqdm   ≥ 4.23.0
-  cdflib ≥ 0.3.9
-  pandas ≥ 0.18.0
-  xarray ≥ 0.11.0
+  requests ≥ 2.0.0
+  Jinja2   ≥ 2.10.0
+  tables   ≥ 3.4.4
+  tqdm     ≥ 4.23.0
+  cdflib   ≥ 0.3.9
+  pandas   ≥ 0.18.0
+  xarray   ≥ 0.11.0
 
-(pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead::
+pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead::
 
-    conda install jinja2 pytables tqdm pandas xarray
+    conda install requests jinja2 pytables tqdm pandas xarray
     pip install viresclient
 
 Recommended setup if starting without Python already
@@ -53,7 +54,7 @@ Recommended setup if starting without Python already
 
 .. note:: For Jupyter notebook users:
 
-  The instructions for first time usage are also provided as a Jupyter notebook which you might find easier to use. Download the notebook to your environment and follow the instructions.
+  The guide for first time usage are also provided as a Jupyter notebook. Download the notebook to your environment and follow the instructions.
 
   https://github.com/smithara/viresclient_examples/blob/master/0_first_usage.ipynb
 
@@ -63,99 +64,24 @@ Recommended setup if starting without Python already
 
   then launch the notebook, ``viresclient_examples/0_first_usage.ipynb``
 
-Access to the service is through the same user account as on the web interface (https://vires.services/) and is enabled through a token. To get a token, log in to the website and click on your name on the top right to access the settings. From here, click on "Manage access tokens" and follow the instructions to create a new token.
+Access to the service is through the same user account as on the web interface (https://vires.services/) and is enabled through an access token (essentially a password). To get a token, log in to the website and click on your name on the top right to access the settings. From here, click on "Manage access tokens" and follow the instructions to create a new token.
 
-While it is possible to enter the server URL and access credentials each time a new request object is created
+To set your token in the client, use either the Python interface:
 
 .. code-block:: python
 
-  from viresclient import SwarmRequest
-
-  # both URL and access token passed as request object's parameters
-  request = SwarmRequest(
-      url="https://vires.services/ows",
-      token="r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-"
-  )
-
-it is more convenient to omit them from the code and store them in a private configuration file
-
-.. code-block:: python
-
-  # access token read from configuration
-  request = SwarmRequest(url="https://vires.services/ows")
-
-  # both default URL and access token read from configuration
-  request = SwarmRequest()
-
-The server access configuration can be set either by command line interface (CLI), Python code, or editing of the configuration file, as described in the following sections.
+  from viresclient import set_token
+  set_token("https://vires.services/ows")
+  # (you will now be prompted to enter the token)
 
-Configuration via CLI
-^^^^^^^^^^^^^^^^^^^^^
-
-The ``viresclient`` shell command can be used to set the server access configuration::
+or the command line tool::
 
   $ viresclient set_token https://vires.services/ows
   Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
 
   $ viresclient set_default_server https://vires.services/ows
 
-Configuration via Python
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Use the following code to store the token in the ``viresclient`` configuration
-
-.. code-block:: python
-
-  from viresclient import ClientConfig
-
-  cc = ClientConfig()
-  cc.set_site_config("https://vires.services/ows", token="r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-")
-  cc.default_url = "https://vires.services/ows"
-  cc.save()
-
-
-Configuration File
-^^^^^^^^^^^^^^^^^^
-
-The client configuration is saved as a text file at ``~/.viresclient.ini``.  This configuration file can edited in a text editor::
-
-  [https://vires.services/ows]
-  token = r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
-
-  [default]
-  url = https://vires.services/ows
-
-When creating the configuration file manually make sure the file is readable by its owner only::
-
-  $ chmod 0600 ~/.viresclient.ini
-  $ ls -l ~/.viresclient.ini
-  -rw-------  1 owner owner  361 May 12 09:12 /home/owner/.viresclient.ini
-
-
-.. note:: For DISC users / developers:
-
-  The user account for the DISC server is separate. A token can be generated in the same way and stored in the configuration alongside the token for other site::
-
-    $ viresclient set_token https://vires.services/ows
-    Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
-
-    $ viresclient set_token https://staging.viresdisc.vires.services/ows
-    Enter access token: VymMHhWjZ-9nSVs-FuPC27ca8C6cOyij
-
-    $ viresclient set_default_server https://vires.services/ows
-
-  Using ``SwarmRequest()`` without the URL parameter will use the default URL set above. To access a non-default server the URL parameter must be used:
-
-  .. code-block:: python
-
-    from viresclient import SwarmRequest
-
-    # request using the default server (https://vires.services/ows)
-    request = SwarmRequest()
-
-    # request to an alternative, non-default server
-    request = SwarmRequest(url="https://staging.viresdisc.vires.services/ows")
-
+See also: see :doc:`config_details`
 
 3. Example use
 --------------
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
@@ -1,17 +1,23 @@
 Release notes
 =============
 
+Changes from 0.4.0 to 0.4.1
+---------------------------
+
+- Added low level data upload API and CLI
+- Added set_token convenience function for quick configuration
+- Changed list of accessible models:
+
+  - Removed ``MCO_SHA_2F``, ``SIFM``
+  - Added ``MF7``, ``LCS-1``
+
 Changes from 0.3.0 to 0.4.0
 ---------------------------
 
 - Fixed issues with running on Windows
-
 - Enforcing Python v3.5+ for installation
-
 - Allowing higher versions of cdflib, pandas, and xarray
-
 - Added CLI configuration for setting server address and token
-
 - Metadata for source lineage is now easier to access (names of original ESA data files, details of models used, and filters applied). These are set as properties of :meth:`viresclient.ReturnedData` (i.e. ``data``) and as metadata (``.attrs``) in the ``Dataset`` returned from ``.as_xarray()``::
 
     data.sources
@@ -24,9 +30,7 @@ Changes from 0.3.0 to 0.4.0
     ds.RangeFilters
 
 - Added access to collections ``SW_OPER_IPDxIRR_2F``
-
 - Added auxiliary data ``F107`` which is the hourly F10.7 value. This is in addition to ``F10_INDEX`` which was already present, which is a daily average.
-
 - Added possibility of accessing multiple collections simultaneously, e.g.::
 
     request.set_collection("SW_OPER_MAGA_LR_1B", "SW_OPER_MAGC_LR_1B")
