From 5d613be468279e63419dabc426af39d9f3abdb8c Mon Sep 17 00:00:00 2001
From: epwalsh <epwalsh10@gmail.com>
Date: Fri, 19 Nov 2021 11:14:39 -0800
Subject: [PATCH] updates docs

---
 .github/workflows/ci.yml  |  2 +-
 Makefile                  |  2 +-
 README.md                 | 53 +++++++++++++++++++++++++++++++++++++++
 docs/source/index.rst     |  4 +--
 docs/source/overview.md   |  3 ---
 docs/source/quickstart.md |  7 ++++++
 setup.py                  |  2 +-
 7 files changed, 64 insertions(+), 9 deletions(-)
 delete mode 100644 docs/source/overview.md
 create mode 100644 docs/source/quickstart.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1197b26..5c3bdcf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -123,7 +123,7 @@ jobs:
         shell: bash
         run: |
           . .venv/bin/activate
-          pip uninstall -y beaker
+          pip uninstall -y beaker-py
 
   release:
     name: Release
diff --git a/Makefile b/Makefile
index 41d74c4..57ca7a4 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
 .PHONY : docs
 docs :
 	rm -rf docs/build/
-	sphinx-autobuild -b html --watch beaker/ docs/source/ docs/build/
+	sphinx-autobuild -b html --watch beaker/ --watch README.md docs/source/ docs/build/
diff --git a/README.md b/README.md
index a4cafc9..c044e6d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,56 @@
 # beaker-py
 
 A [Beaker](https://beaker.org) client for Python.
+
+## Quick links
+
+- [Documentation](https://beaker-py.readthedocs.io/)
+- [PyPI Package](https://pypi.org/project/beaker-py/)
+- [Contributing](https://github.com/allenai/beaker-py/blob/main/CONTRIBUTING.md)
+- [License](https://github.com/allenai/beaker-py/blob/main/LICENSE)
+
+## Installing
+
+### Installing with `pip`
+
+**beaker-py** is available [on PyPI](https://pypi.org/project/beaker-py/). Just run
+
+```bash
+pip install beaker-py
+```
+
+### Installing from source
+
+To install **beaker-py** from source, first clone [the repository](https://github.com/allenai/beaker-py):
+
+```bash
+git clone https://github.com/allenai/beaker-py.git
+cd beaker-py
+```
+
+Then run
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+<!-- start quickstart -->
+
+Create a Beaker client with your Beaker [user token](https://beaker.org/user):
+
+```python
+from beaker import Beaker
+
+beaker = Beaker("my beaker token", workspace="my_org/my_workspace")
+```
+
+You can also create your client from environment variables with:
+
+```python
+# Assumes your user token is set as the environment variable `BEAKER_TOKEN`.
+beaker = Beaker.from_env()
+```
+
+<!-- end quickstart -->
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d3e0b54..e35cab4 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,8 +6,6 @@
 **beaker-py**
 ===============
 
-.. automodule:: beaker
-
 Contents
 --------
 
@@ -16,7 +14,7 @@ Contents
    :caption: Getting started:
 
    installation
-   overview
+   quickstart
    api
    CHANGELOG
 
diff --git a/docs/source/overview.md b/docs/source/overview.md
deleted file mode 100644
index d8d63b4..0000000
--- a/docs/source/overview.md
+++ /dev/null
@@ -1,3 +0,0 @@
-Overview
-========
-
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
new file mode 100644
index 0000000..d96c52a
--- /dev/null
+++ b/docs/source/quickstart.md
@@ -0,0 +1,7 @@
+Quick start
+===========
+
+```{include} ../../README.md
+:start-after: <!-- start quickstart -->
+:end-before: <!-- end quickstart -->
+```
diff --git a/setup.py b/setup.py
index a14c124..8d13026 100644
--- a/setup.py
+++ b/setup.py
@@ -31,7 +31,7 @@ def fix_url_dependencies(req: str) -> str:
     exec(version_file.read(), VERSION)
 
 setup(
-    name="beaker",
+    name="beaker-py",
     version=VERSION["VERSION"],
     description="",
     long_description=open("README.md").read(),