From 83bcf99f47c0fb1bfd452f0eab7875198f845223 Mon Sep 17 00:00:00 2001
From: Jim Myhrberg <contact@jimeh.me>
Date: Mon, 25 Mar 2024 03:02:53 +0000
Subject: [PATCH] docs(readme): flesh out readme

---
 README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 render.go |  2 +-
 2 files changed, 84 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f513523..de9da2a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,85 @@
-# render
+<h1 align="center">
+  go-render
+</h1>
 
-_Warning: Work in progress._
+<p align="center">
+  <strong>
+    A simple and flexible solution to render a value to a <code>io.Writer</code>
+    using different formats based on a format string argument.
+  </strong>
+</p>
 
-Small helper package to make rendering to multiple formats easier using a single
-string value to indicate what format.
+<p align="center">
+  <a href="https://github.com/jimeh/go-render/releases"><img src="https://img.shields.io/github/v/tag/jimeh/go-render?label=release" alt="GitHub tag (latest SemVer)"></a>
+  <a href="https://pkg.go.dev/github.com/jimeh/go-render"><img src="https://img.shields.io/badge/%E2%80%8B-reference-387b97.svg?logo=go&logoColor=white" alt="Go Reference"></a>
+  <a href="https://github.com/jimeh/go-render/issues"><img src="https://img.shields.io/github/issues-raw/jimeh/go-render.svg?style=flat&logo=github&logoColor=white" alt="GitHub issues"></a>
+  <a href="https://github.com/jimeh/go-render/pulls"><img src="https://img.shields.io/github/issues-pr-raw/jimeh/go-render.svg?style=flat&logo=github&logoColor=white" alt="GitHub pull requests"></a>
+  <a href="https://github.com/jimeh/go-render/blob/main/LICENSE"><img src="https://img.shields.io/github/license/jimeh/go-render.svg?style=flat" alt="License Status"></a>
+</p>
+
+Designed around using a custom type/struct to render your output. Thanks to Go's
+marshaling interfaces, you get JSON, YAML, and XML support almost for free.
+While plain text output is supported by the type implementing `io.Reader`,
+`io.WriterTo`, `fmt.Stringer`, and `error` interfaces, or by simply being a type
+which can easily be type cast to a byte slice.
+
+Originally intended to easily implement CLI tools which can output their data as
+plain text, as well as JSON/YAML with a simple switch of a format string. But it
+can just as easily render to any `io.Writer`.
+
+The package is designed to be flexible and extensible with a sensible set of
+defaults accessible via package level functions. You can create your own
+`Renderer` for custom formats, or create new handlers that support custom
+formats.
+
+## Import
+
+```
+import "github.com/jimeh/go-render"
+```
+
+## Usage
+
+Basic usage to render a value to various formats into a `io.Writer`:
+
+```go
+version := &Version{Version: "1.2.1", Stable: true, Latest: false}
+
+// Render version as plain text via fmt.Stringer interface.
+err = render.Pretty(w, "text", version)
+
+// Render version as JSON via marshaling.
+err = render.Pretty(w, "json", version)
+
+// Render version as YAML via marshaling.
+err = render.Pretty(w, "yaml", version)
+
+// Render version as XML via marshaling.
+err = render.Pretty(w, "xml", version)
+```
+
+The above assumes the following `Version` struct:
+
+```go
+type Version struct {
+	Version string `json:"version" yaml:"version" xml:",chardata"`
+	Latest  bool   `json:"latest" yaml:"latest" xml:"latest,attr"`
+	Stable  bool   `json:"stable" yaml:"stable" xml:"stable,attr"`
+}
+
+func (v *Version) String() string {
+	return fmt.Sprintf(
+		"%s (stable: %t, latest: %t)", v.Version, v.Stable, v.Latest,
+	)
+}
+```
+
+## Documentation
+
+Please see the
+[Go Reference](https://pkg.go.dev/github.com/jimeh/go-render#section-documentation)
+for documentation and further examples.
+
+## License
+
+[MIT](https://github.com/jimeh/go-render/blob/main/LICENSE)
diff --git a/render.go b/render.go
index cc3020c..69d6b0c 100644
--- a/render.go
+++ b/render.go
@@ -1,4 +1,4 @@
-// Package render provides a simple and flexible way to render a value to a
+// Package render provides a simple and flexible solutio to render a value to a
 // io.Writer using different formats based on a format string argument.
 //
 // It is designed around using a custom type/struct to render your output.