From 655e7a3b639014b65bf1e6fc9a5d28bd8f47bbff Mon Sep 17 00:00:00 2001
From: LTLA <infinite.monkeys.with.keyboards@gmail.com>
Date: Wed, 24 Apr 2024 08:52:13 -0700
Subject: [PATCH] Fleshed out the README, cleaned up other docs.

---
 CHANGELOG.md  |  6 ++--
 README.md     | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 docs/index.md | 14 +--------
 3 files changed, 86 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 205cc5e..0241820 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,7 +1,5 @@
 # Changelog
 
-## Version 0.1 (development)
+## Version 0.1.0
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+- New release of the Gobbler.
diff --git a/README.md b/README.md
index f0a4296..478ad78 100644
--- a/README.md
+++ b/README.md
@@ -12,4 +12,86 @@
 
 # Python client for the gobbler service
 
-Pretty much as it says on the can; provides an Python client for the [Gobbler service](https://github.com/ArtifactDB/gobbler).
+Pretty much as it says on the tin; provides an Python client for the [Gobbler service](https://github.com/ArtifactDB/gobbler),
+as a sister package to the corresponding [R client](https://github.com/ArtifactDB/gobbler-R).
+To demonstrate, let's spin up a mock Gobbler instance:
+
+```python
+import pygobbler as pyg
+_, staging, registry, url = pyg.start_gobbler()
+```
+
+Administrators are responsible for creating projects:
+
+```python
+pyg.create_project("test", staging=staging, url=url, owners=["akari"])
+```
+
+An authorized user account (in this case, `akari`) can then upload directory of arbitrary files:
+
+```python
+import tempfile
+import os
+tmp = tempfile.mkdtemp()
+with open(os.path.join(tmp, "blah.txt"), "w") as f:
+    f.write("BAR")
+os.mkdir(os.path.join(tmp, "foo"))
+with open(os.path.join(tmp, "foo", "bar.txt"), "w") as f:
+    f.write("1 2 3 4 5 6 7 8 9 10")
+
+pyg.upload_directory(
+    project="test", 
+    asset="foo", 
+    version="bar", 
+    directory=tmp,
+    staging=staging, 
+    url=url
+)
+```
+
+Anyone can fetch or list the contents, either on the same filesystem or remotely via the REST API.
+
+```python
+pyg.list_files("test", "foo", "bar", registry=registry, url=url)
+pyg.fetch_manifest("test", "foo", "bar", registry=registry, url=url)
+pyg.fetch_summary("test", "foo", "bar", registry=registry, url=url)
+pyg.version_path("test", "foo", "bar", registry=registry, url=url)
+```
+
+Project owners can set the permissions to allow other users to add new assets or new versions of existing assets:
+
+```python
+pyg.set_permissions(
+    "test", 
+    uploaders=[ { "id": "alicia", "asset": "foo" } ], 
+    registry=registry, 
+    staging=staging, 
+    url=url
+)
+
+# And then 'alicia' can do:
+pyg.upload_directory(
+    project="test", 
+    asset="foo", 
+    version="bar2", 
+    directory=tmp,
+    staging=staging, 
+    url=url
+)
+```
+
+By default, `uploaders` are untrusted and their uploads will be "probational".
+Owners can approve/reject probational uploads after review.
+
+```python
+pyg.approve_probation("test", "foo", "bar2", staging=staging, url=url)
+```
+
+Finally, administrators can delete projects, though this should be done sparingly.
+
+```python
+pyg.remove_project("test", staging=staging, url=url)
+```
+
+Check out the [API documentation](https://artifactdb.github.io/gobbler-py/) for more details on each function.
+For the concepts underlying the Gobbler itself, check out the [repository](https://github.com/ArtifactDB/gobbler) for a detailed explanation.
diff --git a/docs/index.md b/docs/index.md
index 583c019..0c86e65 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,18 +1,6 @@
 # pygobbler
 
-Add a short description here!
-
-
-## Note
-
-> This is the main page of your project's [Sphinx] documentation. It is
-> formatted in [Markdown]. Add additional pages by creating md-files in
-> `docs` or rst-files (formatted in [reStructuredText]) and adding links to
-> them in the `Contents` section below.
->
-> Please check [Sphinx] and [MyST] for more information
-> about how to document your project and how to configure your preferences.
-
+Python client for the [Gobbler](https://github.com/ArtifactDB/gobbler) service.
 
 ## Contents