doc: update instructions for client libraries

* include Nat's review and fixes

Co-authored-by: nmdefries <[email protected]>

Author: dshemetov

docs/api/client_libraries.md

@@ -6,83 +6,81 @@ nav_order: 1
 
 # Epidata API Client Libraries
 
+To access Delphi Epidata programmatically, we recommend our client libraries:
+
+- R: [epidatr](https://cmu-delphi.github.io/epidatr/),
+- Python: [delphi-epidata](https://pypi.org/project/delphi-epidata/) (soon to be replaced with [epidatpy](https://github.com/cmu-delphi/epidatpy)),
+- Javascript: [delphi-epidata](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.js).
+
 For anyone looking for COVIDCast data, please visit our [COVIDCast Libraries](covidcast_clients.md).
 
-A full-featured Epidata client for R is available at
-[epidatr](https://github.com/cmu-delphi/epidatr) and
-[also on CRAN](https://cran.r-project.org/web/packages/epidatr/index.html).
-
-We are currently working on a new full-featured Epidata client for Python. It is not ready
-for release yet, but you can track our development progress and help us test it out at
-[epidatpy](https://github.com/cmu-delphi/epidatpy).
-
-In the meantime, minimalist Epidata clients remain available for
-[Python](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.py),
-[JavaScript](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.js),
-and
-[R (legacy)](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.R).
-The following samples show how to import the library and fetch Delphi's COVID-19
-Surveillance Streams from Facebook Survey CLI for county 06001, and days
+The following samples show how to import the library and fetch Delphi's
+COVID-19 Surveillance Streams from Facebook Survey CLI for county 06001 and days
 `20200401` and `20200405-20200414` (11 days total).
 
 ### R
 
-````R
-# [Optional] configure your API key, if desired
-# Interactive. See https://cmu-delphi.github.io/epidatr/articles/epidatr.html#api-keys for details.
+Install [`epidatr` from CRAN](https://cran.r-project.org/package=epidatr)
+with `install.packages("epidatr")`.
+
+```R
+# Configure API key interactively, if needed. See
+# https://cmu-delphi.github.io/epidatr/articles/epidatr.html#api-keys for details.
 #save_api_key()
-# Import
 library(epidatr)
-# Fetch data
 res <- pub_covidcast('fb-survey', 'smoothed_cli', 'county', 'day', geo_values = '06001',
                      time_values = c(20200401, 20200405:20200414))
 cat(res)
-````
+```
 
 ### Python
 
-Optionally install the [package from PyPI](https://pypi.org/project/delphi-epidata/) using pip(env):
-````bash
-pip install delphi-epidata
-````
+Install [`delphi-epidata` from PyPI](https://pypi.org/project/delphi-epidata/) with
+`pip install delphi-epidata`.
 
-Otherwise, place
-[`delphi_epidata.py`](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.py)
-in the same directory as your Python script.
-
-````python
-# Import
+```python
 from delphi_epidata import Epidata
-# [Optional] configure your API key, if desired
+# Configure API key, if needed.
 #Epidata.auth = ('epidata', <your API key>)
-# Fetch data
 res = Epidata.covidcast('fb-survey', 'smoothed_cli', 'day', 'county', [20200401, Epidata.range(20200405, 20200414)], '06001')
 print(res['result'], res['message'], len(res['epidata']))
-````
+```
 
 ### JavaScript (in a web browser)
 
-The minimalist JavaScript client does not currently support API keys. If you need API key support in JavaScript, contact [email protected].
+The minimalist JavaScript client does not currently support API keys.
+If you need API key support in JavaScript, contact [email protected].
 
-````html
-<!-- Imports -->
+```html
 <script src="delphi_epidata.js"></script>
-<!-- Fetch data -->
 <script>
-  EpidataAsync.covidcast('fb-survey', 'smoothed_cli', 'day', 'county', [20200401, EpidataAsync.range(20200405, 20200414)], '06001').then((res) => {
-    console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
+  EpidataAsync.covidcast(
+    "fb-survey",
+    "smoothed_cli",
+    "day",
+    "county",
+    [20200401, EpidataAsync.range(20200405, 20200414)],
+    "06001"
+  ).then((res) => {
+    console.log(
+      res.result,
+      res.message,
+      res.epidata != null ? res.epidata.length : 0
+    );
   });
 </script>
-````
+```
 
 ### R (legacy)
 
+The old Delphi Epidata R client is available
+[here](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R),
+but its use is discouraged.
+
 ```R
-# [Optional] configure your API key, if desired
+# Configure API key, if needed.
 #option('epidata.auth', <your API key>)
-# Import
 source('delphi_epidata.R')
-# Fetch data
 res <- Epidata$covidcast('fb-survey', 'smoothed_cli', 'day', 'county', list(20200401, Epidata$range(20200405, 20200414)), '06001')
 cat(paste(res$result, res$message, length(res$epidata), "\n"))
 ```

docs/api/covidcast_clients.md

@@ -6,15 +6,15 @@ nav_order: 1
 
 # COVIDcast Libraries
 
-Dedicated COVIDcast access and analysis libraries are available for several languages:
+To access COVIDcast data, we recommend using the following client libraries:
 
-* R: [covidcast](https://cmu-delphi.github.io/covidcast/covidcastR/)
-* Python: [covidcast](https://cmu-delphi.github.io/covidcast/covidcast-py/html/)
+- R: [epidatr](https://cmu-delphi.github.io/epidatr/),
+- Python: [covidcast](https://cmu-delphi.github.io/covidcast/covidcast-py/html/) (soon to be replaced with [epidatpy](https://github.com/cmu-delphi/epidatpy)).
 
 These packages provide a convenient way to obtain COVIDcast data as a data frame
-ready to be used in further analyses and provide convenient mapping and
-analysis functions. For installation instructions and examples, consult their
-respective webpages.
+ready to be used in further analyses and provide convenient mapping and analysis
+functions. For installation instructions and examples, consult their respective
+webpages.
 
-
-To access Epidata datasets on other diseases, visit our [Epidata API Client Libraries)](client_libraries.md) documentation.
+To access Epidata datasets on other diseases, visit our
+[Epidata API Client Libraries](client_libraries.md) documentation.