updates docs

.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

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/

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 -->

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
 

docs/source/quickstart.md

@@ -0,0 +1,7 @@
+Quick start
+===========
+
+```{include} ../../README.md
+:start-after: <!-- start quickstart -->
+:end-before: <!-- end quickstart -->
+```

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(),