Update docs with enhanced usage info (#38)

* Update docs with enhanced usage info

Signed-off-by: Yoriyasu Yano <430092+yorinasub17@users.noreply.github.com>

* Fix incorrect “it’s” with “its”

* Make sure to bind /docs in docker docs so that output can be synced to host

Signed-off-by: Yoriyasu Yano <430092+yorinasub17@users.noreply.github.com>

* docs: use -J vendor

---------

Signed-off-by: Yoriyasu Yano <430092+yorinasub17@users.noreply.github.com>
Co-authored-by: Jeroen Op 't Eynde <jeroen@simplistic.be>

Author: yorinasub17

README.md

@@ -39,7 +39,7 @@ Jsonnet itself does not know traditional packages, classes or similar.
 
 For documentation and distribution purposes however, it seems reasonable to introduce a concept of **loose packages**, defined as a single importable file, holding all of your **public API**.
 
-As an example, a hypothetical `url` library could define it's package like above example does.
+As an example, a hypothetical `url` library could define its package like above example does.
 
 Packages are defined by including assigning a `d.pkg` call to a key literally named `#` (hash). All fields, including nested packages, of the same object having the `#` key belong to that package.
 
@@ -54,7 +54,7 @@ Most common part of an API will be functions. These are annotated in a similar f
 }
 ```
 
-Along the actual function definition, a _docsonnet_ key is added, with the functions name prefixed by the familiar `#` as it's name.  
+Along the actual function definition, a _docsonnet_ key is added, with the functions name prefixed by the familiar `#` as its name.
 Above example defines `myFunc` as a function, that greets the user and takes a single argument of type `string`.
 
 ### Objects
@@ -73,18 +73,71 @@ Such an object might need a description as well, so you can also annotate it:
 }
 ```
 
-Again, the naming rule `#` joined with the fields name must be followed, so the `docsonnet` utility can automatically join together the contents of your object with it's annotated description.
+Again, the naming rule `#` joined with the fields name must be followed, so the `docsonnet` utility can automatically join together the contents of your object with its annotated description.
 
-## FAQ
 
-#### Do my projects need to have `doc-util` installed to vendor/?
+## Usage
+
+Once you have a Jsonnet library annotated with `doc-util`, you can generate the docs using one of three ways:
+
+- [Jsonnet renderer](#jsonnet-renderer)
+- [docsonnet binary](#docsonnet-binary)
+- [docsonnet docker image](#docsonnet-docker-image)
+
+### Jsonnet renderer
+
+The docs can be rendered using Jsonnet with the
+[render](https://github.com/jsonnet-libs/docsonnet/tree/master/doc-util#fn-render) function.
+
+In your library source, add a file `docs.jsonnet` (assuming your library entrypoint is `main.libsonnet`) with the
+following contents:
+
+```jsonnet
+local d = import 'github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet';
+d.render(import 'main.libsonnet')
+```
+
+Then, you can render the markdown to the `docs/` folder using the following command:
+
+```
+jsonnet -J vendor -S -c -m docs/ docs.jsonnet
+```
+
+Note that this requires `doc-util` to be installed to `vendor/` to work properly.
+
+### docsonnet binary
+
+Alternatively, the docs can be rendered using the `docsonnet` go binary. The `docsonnet` binary embeds the `doc-util`
+library, avoiding the need to have `doc-util` installed.
 
-No! The `docsonnet` binary comes included with it, and during normal Jsonnet use the docsonnet keys will never be accessed, so your Jsonnet runs just fine without.
+You can install the `docsonnet` binary using `go install`:
 
-> **Note** 
-> 
+```
+go install github.com/jsonnet-libs/docsonnet@master
+```
+
+Once the binary is installed, you can generate the docs by passing it the main entrypoint to your Jsonnet library:
+
+```
+docsonnet main.libsonnet
+```
+
+> **Note**
+>
 > Linters like [jsonnet-lint](https://pkg.go.dev/github.com/google/go-jsonnet/linter) or `tk lint` require the imports to be resolvable, so you should add `doc-util` to `vendor/` when using these linters.
 
+### docsonnet docker image
+
+You can also use the [docker image](https://hub.docker.com/r/jsonnetlibs/docsonnet) which contains the `docsonnet`
+binary if you do not wish to set up go or install the binary locally:
+
+```
+docker run --rm -v "$(pwd):/src" -v "$(pwd)/docs:/docs" jsonnetlibs/docsonnet /src/main.libsonnet
+```
+
+
+## FAQ
+
 #### What's wrong with comments? Why not parse regular comments?
 
 I had some attempts on this, especially because it feels more natural. However, the language properties of Jsonnet make this quite challenging:
@@ -132,4 +185,4 @@ This will all happen transparently, without any user interaction
 
 Because the Docsonnet gives you the missing logical representation of your Jsonnet library, it enables straight forward implementation of other language tooling, such as **code-completion**.
 
-Instead of inferring what fields are available for a library, we can _just_ look at it's docsonnet and provide the fields specified there, along with nice descriptions and argument types.
+Instead of inferring what fields are available for a library, we can _just_ look at its docsonnet and provide the fields specified there, along with nice descriptions and argument types.