Merge pull request #45 from cmu-delphi/upd-doc

docs: adds parameter descriptions for endpoints and incorporates the latest epidatr docs updates

Author: JavierMtzRdz

docs/conf.py

@@ -31,7 +31,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", "sphinx_autodoc_typehints", "nbsphinx"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "nbsphinx"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/epidatpy.rst

@@ -1,5 +1,5 @@
 epidatpy Reference
-================
+==================
 
 .. toctree::
    :maxdepth: 4
@@ -13,7 +13,7 @@ epidatpy.request module
    :show-inheritance:
 
 epidatpy._endpoints module
------------------------
+--------------------------
 
 .. automodule:: epidatpy._endpoints
    :members:

docs/getting_started.ipynb

@@ -181,6 +181,65 @@
     ").df()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also request all versions of the data issued within a specific time range using the `issues` argument. `issues` can also take a single date.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# See how the estimate for a SINGLE day (March 1, 2021) evolved\n",
+    "# by fetching all issues reported between March and April 2021.\n",
+    "epidata.pub_covidcast(\n",
+    "    data_source=\"fb-survey\",\n",
+    "    signals=\"smoothed_cli\",\n",
+    "    geo_type=\"state\",\n",
+    "    time_type=\"day\",\n",
+    "    geo_values=\"pa\",\n",
+    "    time_values=\"2021-03-01\",\n",
+    "    issues=EpiRange(\"2021-03-01\", \"2021-04-30\"),\n",
+    ").df()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, we can use the `lag` argument to request only data that was reported a certain number of days after the event.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Fetch survey data for January 2021, but ONLY include data\n",
+    "# that was issued exactly 2 days after it was collected.\n",
+    "epidata.pub_covidcast(\n",
+    "    data_source=\"fb-survey\",\n",
+    "    signals=\"smoothed_cli\",\n",
+    "    geo_type=\"state\",\n",
+    "    time_type=\"day\",\n",
+    "    geo_values=\"pa\",\n",
+    "    time_values=EpiRange(20210101, 20210131),\n",
+    "    lag=2,\n",
+    ").df()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "See detail notebook about [versioned data](versioned_data.ipynb) for details and more ways to specify versioned data.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -234,9 +293,9 @@
     "\n",
     "Most data is only available for the US. Select endpoints report other countries at the national and/or regional levels. Endpoint descriptions explicitly state when they cover non-US locations.\n",
     "\n",
-    "For endpoints that report US data, see the\n",
+    "For the main endpoints that report US data, see the\n",
     "[geographic coding documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html)\n",
-    "for available geographic levels.\n",
+    "for available geographic levels. Documentation for the other endpoints is available [here](https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html).\n",
     "\n",
     "## International data\n",
     "\n",

docs/index.rst

@@ -45,7 +45,7 @@ Note that for the time being, the private endpoints (i.e. those prefixed with
 ``pvt``) will require additional permissions (contact us for more information).
 
 Documentation Contents
-===============
+======================
 
 .. toctree::
    :maxdepth: 1