doc: iterate on all documentation pages, README

* switch default venv from env to .venv for uv
* update gitignore

Author: dshemetov

.gitignore

@@ -8,5 +8,4 @@ __pycache__
 dist/
 build/
 docs/_build
-env/
-venv/
+.venv/

Makefile

@@ -1,33 +1,33 @@
 .PHONY = venv, lint, test, clean, release
 
 venv:
-	python3.8 -m venv env
+	python3.8 -m venv .venv
 
 install: venv
-	env/bin/python -m pip install --upgrade pip
-	env/bin/pip install -e ".[dev]"
+	.venv/bin/python -m pip install --upgrade pip
+	.venv/bin/pip install -e ".[dev]"
 
 lint_ruff:
-	env/bin/ruff check epidatpy tests
+	.venv/bin/ruff check epidatpy tests
 
 lint_mypy:
-	env/bin/mypy epidatpy tests
+	.venv/bin/mypy epidatpy tests
 
 lint_pylint:
-	env/bin/pylint epidatpy tests
+	.venv/bin/pylint epidatpy tests
 
 lint: lint_ruff lint_mypy lint_pylint
 
 format:
-	env/bin/ruff format epidatpy tests
+	.venv/bin/ruff format epidatpy tests
 
 test:
-	env/bin/pytest .
+	.venv/bin/pytest .
 
 doc:
 	@pandoc --version >/dev/null 2>&1 || (echo "ERROR: pandoc is required (install via your platform's package manager)"; exit 1)
-	env/bin/sphinx-build -b html docs docs/_build
-	env/bin/python -m webbrowser -t "docs/_build/index.html"
+	.venv/bin/sphinx-build -b html docs docs/_build
+	.venv/bin/python -m webbrowser -t "docs/_build/index.html"
 
 clean_doc:
 	rm -rf docs/_build
@@ -45,7 +45,7 @@ clean_python:
 clean: clean_doc clean_build clean_python
 
 release: clean lint test
-	env/bin/python -m build --sdist --wheel
+	.venv/bin/python -m build --sdist --wheel
 
 upload: release
-	env/bin/twine upload dist/*
+	.venv/bin/twine upload dist/*

README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url] [![PyPi][pypi-image]][pypi-url] [![Read the Docs][docs-image]][docs-url]
 
-A Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/). Still in development.
+The Python client for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/).
 
 ## Install
 
@@ -18,7 +18,23 @@ pip install epidatpy
 
 ## Usage
 
-TODO
+```py
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+
+# All calls using the `epidata` object will now be cached for 7 days
+epidata = EpiDataContext(use_cache=True, cache_max_age_days=7)
+
+# Obtain a DataFrame of the most up-to-date version of the smoothed covid-like illness (CLI)
+# signal from the COVID-19 Trends and Impact survey for the US
+epidata.pub_covidcast(
+    data_source="jhu-csse",
+    signals="confirmed_cumulative_num",
+    geo_type="nation",
+    time_type="day",
+    geo_values="us",
+    time_values=EpiRange(20210405, 20210410),
+).df()
+```
 
 ## Development
 
@@ -35,8 +51,8 @@ make release  # upload the current version to pypi
 make clean    # clean build and docs artifacts
 ```
 
-Building the documentation additionally requires the Pandoc package. These commands can be used
-to install the package on common platforms (see the
+Building the documentation additionally requires the Pandoc package. These
+commands can be used to install the package on common platforms (see the
 [official documentation](https://pandoc.org/installing.html) for more options):
 
 ```sh

docs/conf.py

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

docs/epidatpy.rst

@@ -4,17 +4,6 @@ epidatpy Reference
 .. toctree::
    :maxdepth: 4
 
-Submodules
-----------
-
-Module contents
----------------
-
-.. automodule:: epidatpy
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 epidatpy.request module
 -----------------------
 
@@ -23,11 +12,11 @@ epidatpy.request module
    :undoc-members:
    :show-inheritance:
 
-epidatpy.async\_request module
-------------------------------
+epidatpy._endpoints module
+-----------------------
 
-.. automodule:: epidatpy.async_request
+.. automodule:: epidatpy._endpoints
    :members:
    :undoc-members:
    :show-inheritance:
-
+   :exclude-members: get_wildcard_equivalent_dates