Merge pull request #40 from cmu-delphi/rzatserkovnyi/docs

[WIP] Port R docs vignettes to epidatpy

Author: dshemetov

.gitignore

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

Makefile

@@ -1,34 +1,35 @@
 .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 .
 
-docs:
-	env/bin/sphinx-build -b html docs docs/_build
-	env/bin/python -m webbrowser -t "docs/_build/index.html"
+doc:
+	@pandoc --version >/dev/null 2>&1 || (echo "ERROR: pandoc is required (install via your platform's package manager)"; exit 1)
+	.venv/bin/sphinx-build -b html docs docs/_build
+	.venv/bin/python -m webbrowser -t "docs/_build/index.html"
 
-clean_docs:
+clean_doc:
 	rm -rf docs/_build
 
 clean_build:
@@ -41,10 +42,10 @@ clean_python:
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -fr {} +
 
-clean: clean_docs clean_build 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,6 +51,21 @@ 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
+[official documentation](https://pandoc.org/installing.html) for more options):
+
+```sh
+# Linux (Debian/Ubuntu)
+sudo apt-get install pandoc
+
+# OS X / Linux (with Homebrew)
+brew install pandoc
+
+# Windows (with Chocolatey)
+choco install pandoc
+```
+
 ### Release Process
 
 The release consists of multiple steps which can be all done via the GitHub website:

docs/conf.py

@@ -31,11 +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'
-]
+extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints", "nbsphinx"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -84,3 +80,8 @@
 
 # https://pypi.org/project/sphinx-autodoc-typehints/
 always_document_param_types = True
+
+# https://nbsphinx.readthedocs.io/
+nbsphinx_prompt_width = 0
+nbsphinx_input_prompt = "%.0s"
+nbsphinx_output_prompt = "%.0s"

docs/covidcast_examples.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