Documentation updates

Author: bcspragu

README.md

@@ -2,7 +2,7 @@
 
 [![CI Workflow](https://github.com/Silicon-Ally/rules_oapi_codegen/actions/workflows/build.yml/badge.svg)](https://github.com/Silicon-Ally/rules_oapi_codegen/actions?query=branch%3Amain)
 
-`rules_oapi_codegen` provides [Bazel](https://bazel.build) rules for generating Go code from OpenAPI 3.0 definitions. It uses github.com/deepmap/oapi-codegen to provide this functionality.
+`rules_oapi_codegen` provides [Bazel](https://bazel.build) rules for generating Go code from OpenAPI 3.0 definitions. It uses [deepmap/oapi-codegen](https://github.com/deepmap/oapi-codegen) to provide this functionality.
 
 ## Usage
 
@@ -23,7 +23,7 @@ oapi_codegen_go(
 
 ## Example
 
-The `example` directory provides [the standard Petstore example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/vv3.0/petstore.yaml), see [the example/ README](/example/README.md) for more details.
+The `example` directory provides [the standard OpenAPI Petstore example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/vv3.0/petstore.yaml), see [the example/ README](/example/README.md) for more details.
 
 ## Contributing
 

docs/BUILD.bazel

@@ -0,0 +1,10 @@
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+stardoc(
+    name = "oapi_codegen",
+    out = "oapi_codegen.md",
+    input = "//oapi_codegen:def.bzl",
+    deps = [
+        "@io_bazel_rules_go//go:def",
+    ],
+)

docs/oapi_codegen.md

@@ -0,0 +1,31 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="oapi_codegen_go"></a>
+
+## oapi_codegen_go
+
+<pre>
+oapi_codegen_go(<a href="#oapi_codegen_go-name">name</a>, <a href="#oapi_codegen_go-spec">spec</a>, <a href="#oapi_codegen_go-importpath">importpath</a>, <a href="#oapi_codegen_go-visibility">visibility</a>, <a href="#oapi_codegen_go-kwargs">kwargs</a>)
+</pre>
+
+Generates Go bindings for an OpenAPI 3.0 spec.
+
+This rule runs [oapi-codegen](https://github.com/deepmap/oapi-codegen) to
+produce a generated Go library providing, among other things, a strictly
+typed API stub interface to implement your API against.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="oapi_codegen_go-name"></a>name |  A unique name for this rule.   |  none |
+| <a id="oapi_codegen_go-spec"></a>spec |  The OpenAPI 3.0 YAML specification for your API, must be self-contained.   |  none |
+| <a id="oapi_codegen_go-importpath"></a>importpath |  The importpath of the directory the rule is defined in, like 'github.com/&lt;org&gt;/&lt;repo&gt;/path/to/dir/api'. This is the import path of the generated Go library   |  none |
+| <a id="oapi_codegen_go-visibility"></a>visibility |  The visibility of the generated go_library target.   |  none |
+| <a id="oapi_codegen_go-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+
+

docs/release.md

@@ -0,0 +1,28 @@
+# Cutting a new release
+
+1. Submit all the code you want to be in the release.
+2. Create a new tag for the release with `git tag vX.Y.Z`
+    - You can get the current latest tag with `git describe --tags --abbrev=0`
+3. Push the tag with `git push origin vX.Y.Z`
+4. Create an archive with `git archive --output=rules_oapi_codegen-vX.Y.Z.zip vX.Y.Z`
+5. Create the release with `gh release create vX.Y.Z rules_oapi_codegen-vX.Y.Z.zip --generate-notes`
+6. Get a SHA256 digest of the archive with `sha256sum rules_oapi_codegen-vX.Y.Z.zip`
+7. Update the description of the release, prepending the usage instructions.
+    - They should look something like:
+    ````markdown
+    # `WORKSPACE` code
+
+    ```bazel
+    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+    http_archive(
+        name = "com_siliconally_rules_oapi_codegen",
+        sha256 = "<sha256sum output>",
+        urls = [
+            "https://github.com/Silicon-Ally/rules_oapi_codegen/releases/download/vX.Y.Z/rules_oapi_codegen-vX.Y.Z.zip",
+        ],
+    )
+    ```
+    ````
+
+You're done! Congrats on the successful release.

oapi_codegen/BUILD.bazel

@@ -0,0 +1 @@
+exports_files(["def.bzl"])

oapi_codegen/def.bzl

@@ -1,6 +1,21 @@
 load("@io_bazel_rules_go//go:def.bzl", "go_library")
 
 def oapi_codegen_go(name, spec, importpath, visibility, **kwargs):
+    """Generates Go bindings for an OpenAPI 3.0 spec.
+
+    This rule runs [oapi-codegen](https://github.com/deepmap/oapi-codegen) to
+    produce a generated Go library providing, among other things, a strictly
+    typed API stub interface to implement your API against.
+
+    Args:
+      name: A unique name for this rule.
+      spec: The OpenAPI 3.0 YAML specification for your API, must be self-contained.
+      importpath: The importpath of the directory the rule is defined in, like
+        'github.com/<org>/<repo>/path/to/dir/api'. This is the import path of
+        the generated Go library
+      visibility: The visibility of the generated go_library target.
+    """
+
     codegen_args = {
         "name": name,
         "spec": spec,