docs: doc and link updates

Author: TristanSpeakEasy

README.md

@@ -2,8 +2,10 @@
 
 The Speakeasy OpenAPI module provides a set of packages and tools for working with OpenAPI Specification documents.
 
+Documentation for the packages can be found in the [GoDoc documentation.](https://pkg.go.dev/github.com/speakeasy-api/openapi)
+
 ## Main Packages
 
-### [arazzo](./arazzo/README.md)
+### [arazzo](./arazzo)
 
 The `arazzo` package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.

arazzo/README.md

@@ -22,18 +22,35 @@ import (
 func main() {
     ctx := context.Background()
 
-    f, err := os.Open("arazzo.yaml")
+    r, err := os.Open("testdata/speakeasybar.arazzo.yaml")
     if err != nil {
         panic(err)
     }
+    defer r.Close()
 
-    arazzo, validationErrs, err := arazzo.Unmarshal(ctx, f)
+    // Unmarshal the Arazzo document which will also validate it against the Arazzo Specification
+    a, validationErrs, err := arazzo.Unmarshal(ctx, r)
     if err != nil {
         panic(err)
     }
 
-    fmt.Printf("%+v\n", arazzo)
-    fmt.Printf("%+v\n", validationErrs)
+    // Validation errors are returned separately from any errors that block the document from being unmarshalled
+    // allowing an invalid document to be mutated and fixed before being marshalled again
+    for _, err := range validationErrs {
+        fmt.Println(err.Error())
+    }
+
+    // Mutate the document by just modifying the returned Arazzo object
+    a.Info.Title = "Speakeasy Bar Workflows"
+
+    buf := bytes.NewBuffer([]byte{})
+
+    // Marshal the document to a writer
+    if err := arazzo.Marshal(ctx, a, buf); err != nil {
+        panic(err)
+    }
+
+    fmt.Println(buf.String())
 }
 ```
 

arazzo/arazzo_examples_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/speakeasy-api/openapi/pointer"
 )
 
+// The below examples should be copied into the README.md file if every changed TODO: automate this
 func Example_readAndMutate() {
 	ctx := context.Background()
 
@@ -44,24 +45,6 @@ func Example_readAndMutate() {
 	fmt.Println(buf.String())
 }
 
-// The below examples should be copied into the README.md file if every changed TODO: automate this
-func Example_reading() {
-	ctx := context.Background()
-
-	f, err := os.Open("arazzo.yaml")
-	if err != nil {
-		panic(err)
-	}
-
-	arazzo, validationErrs, err := arazzo.Unmarshal(ctx, f)
-	if err != nil {
-		panic(err)
-	}
-
-	fmt.Printf("%+v\n", arazzo)
-	fmt.Printf("%+v\n", validationErrs)
-}
-
 func Example_creating() {
 	ctx := context.Background()