PR feedback

* Remove redoc * Upgrade docusaurus * Add spicedb commands page
authzed · Apr 1, 2022 · 8c2f3fa · 8c2f3fa
1 parent 9ed58c0
commit 8c2f3fa
Show file tree

Hide file tree

Showing 13 changed files with 647 additions and 1,757 deletions.
diff --git a/docs/guides/installing.md b/docs/guides/installing.md
diff --git a/docs/guides/rest-api.md b/docs/guides/rest-api.md
diff --git a/docs/guides/schema.md b/docs/guides/schema.md
@@ -1,4 +1,4 @@
-# Developing Your Schema
+# Developing a Schema
 
 import {InlinePlayground} from '../../src/components/InlinePlayground';
 

diff --git a/docs/guides/writing-relationships.md b/docs/guides/writing-relationships.md
@@ -1,56 +1,17 @@
 # Writing Relationships
 
-:::note
-Want to learn more about writing relationships to SpiceDB, the various strategies and their pros and cons? Read our [blog post about writing relationships]
-:::
-
-[blog post about writing relationships]: https://authzed.com/blog/writing-relationships-to-spicedb/
-
 In [SpiceDB], a permissions system is defined by two items: the [schema] which defines *how* data can be represented, and the *relationships*, defining the way the objects are actually related to one another.
 
 [schema]: /guides/schema
 [SpiceDB]: https://github.com/authzed/spicedb
 
 It is the application's responsibility to keep the relationships within SpiceDB up-to-date and reflecting the state of the application; how an application does so can vary based on the specifics of the application, so below we outline a few approaches.
 
-## Two writes + commit
-
-The most common and straightforward way to store relationships in SpiceDB is to use a 2 phase commit-like approach, making use of a transaction from the relational database along with a [WriteRelationships] call to SpiceDB.
-
-[WriteRelationships]: https://buf.build/authzed/api/docs/main/authzed.api.v1#WriteRelationships
-
-```python title='Example of a 2PC-like approach'
-# Open the database transaction
-try:
-    with db.transaction() as transaction:
-        # Update the relationship in the database.
-        document = Document(
-            id="somedoc",
-            owner=some_user,
-        )
-        transaction.add(document)
-
-        # Add the relationship(s) in SpiceDB.
-        resp = client.WriteRelationships(...)
-
-        # Store the ZedToken we've received.
-        document.zedtoken = result.written_at
-
-        # Transaction is committed on close
-except:
-    # Delete the relationship(s) just written
-    client.DeleteRelationships(...)
-    raise
-```
-
-## Streaming commits
-
-Another approach is to stream updates to both a relational database and SpiceDB via a third party streaming system such as [Kafka], using a pattern known as [Command Query Responsibility Segregation] (CQRS)
-
-[Kafka]: https://kafka.apache.org/
-[Command Query Responsibility Segregation]: https://www.confluent.io/blog/event-sourcing-cqrs-stream-processing-apache-kafka-whats-connection/
+:::note
+Want to learn more about writing relationships to SpiceDB, the various strategies and their pros and cons? Read our [blog post about writing relationships]
+:::
 
-In this design, any updates to the relationships in both databases are published as **events** to the streaming service, with each event being consumed by a system which performs the updates in both the database and in SpiceDB.
+[blog post about writing relationships]: https://authzed.com/blog/writing-relationships-to-spicedb/
 
 ## SpiceDB-only relationships
 
@@ -79,6 +40,41 @@ Rather, this information can be stored solely in SpiceDB, and accessed by the ap
 [ReadRelationships]: https://buf.build/authzed/api/docs/main/authzed.api.v1#ReadRelationships
 [ExpandPermissionsTree]: https://buf.build/authzed/api/docs/main/authzed.api.v1#ExpandPermissionTree
 
+## Two writes + commit
+
+The most common and straightforward way to store relationships in SpiceDB is to use a 2 phase commit-like approach, making use of a transaction from the relational database along with a [WriteRelationships] call to SpiceDB.
+
+[WriteRelationships]: https://buf.build/authzed/api/docs/main/authzed.api.v1#WriteRelationships
+
+```python title='Example of a 2PC-like approach'
+try:
+  tx = db.transaction()
+
+  # Write relationships during a transaction so that it can be aborted on exception
+  resp = spicedb_client.WriteRelationships(...) 
+
+  tx.add(db_models.Document(
+    id=request.document_id,
+    owner=user_id,
+    zedtoken=resp.written_at
+  )) 
+  tx.commit() 
+except:
+  # Delete relationships written to SpiceDB and re-raise the exception
+  tx.abort()
+  spicedb_client.DeleteRelationships(...)
+  raise
+```
+
+## Streaming commits
+
+Another approach is to stream updates to both a relational database and SpiceDB via a third party streaming system such as [Kafka], using a pattern known as [Command Query Responsibility Segregation] (CQRS)
+
+[Kafka]: https://kafka.apache.org/
+[Command Query Responsibility Segregation]: https://www.confluent.io/blog/event-sourcing-cqrs-stream-processing-apache-kafka-whats-connection/
+
+In this design, any updates to the relationships in both databases are published as **events** to the streaming service, with each event being consumed by a system which performs the updates in both the database and in SpiceDB.
+
 ## Asynchronous Updates
 
 **NOTE:** This should *only* be used if your application supports less rigid consistency guarantees.

diff --git a/docs/overview.md b/docs/overview.md
@@ -16,7 +16,7 @@ Once stored, data can be performantly queried to answer questions such as "Does
 
 ## Getting Started
 
-1. Log into the [Authzed dashboard] to create a serverless SpiceDB instance or [Install SpiceDB locally]
+1. Log into the [Authzed dashboard] to create a serverless SpiceDB instance or [run SpiceDB] yourself.
 2. Start the [Protecting Your First App] guide
 
 ## Other Resources
@@ -28,7 +28,7 @@ Once stored, data can be performantly queried to answer questions such as "Does
 - Explore the gRPC API documentation on the [Buf Registry]
 - [Install zed] and interact with a live database
 
-[Install SpiceDB locally]: /guides/installing
+[run SpiceDB]: /spicedb/installing
 [Authzed]: https://authzed.com
 [Authzed dashboard]: https://app.authzed.com
 [SpiceDB]: https://github.com/authzed/spicedb

diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -151,7 +151,7 @@ For more information, you can read [this blog post][udr-post].
 
 ## Wildcard
 
-A *wildcard* type declared on a `relation` allows for a grant of permission to *all* subjects of the type specified, making any permission that references that relation **public** for all subjects of that type.
+A _wildcard_ type declared on a `relation` allows for a grant of permission to _all_ subjects of the type specified, making any permission that references that relation **public** for all subjects of that type.
 
 ## Zanzibar