From 373fe21b346cbf3ce58331ff1997dca8f01d4cc3 Mon Sep 17 00:00:00 2001
From: Samuel Williams <samuel.williams@oriontransfer.co.nz>
Date: Sun, 10 Mar 2024 13:15:06 +1300
Subject: [PATCH] Fix documentation.

---
 gems.rb                          |  2 ++
 guides/getting-started/readme.md | 50 ++++++++++++++++++++++++++++++++
 guides/links.yaml                |  2 ++
 protocol-hpack.gemspec           |  6 +++-
 readme.md                        | 27 ++---------------
 5 files changed, 61 insertions(+), 26 deletions(-)
 create mode 100644 guides/getting-started/readme.md
 create mode 100644 guides/links.yaml

diff --git a/gems.rb b/gems.rb
index 682b68b..22312c4 100644
--- a/gems.rb
+++ b/gems.rb
@@ -21,4 +21,6 @@
 group :maintenance, optional: true do
 	gem "bake-gem"
 	gem "bake-modernize"
+	
+	gem "utopia-project"
 end
diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md
new file mode 100644
index 0000000..eef2abe
--- /dev/null
+++ b/guides/getting-started/readme.md
@@ -0,0 +1,50 @@
+# Getting Started
+
+This guide explains how to use the `protocol-hpack` gem to compress and decompress HTTP/2 headers using HPACK.
+
+## Installation
+
+Add the gem to your project:
+
+``` shell
+$ bundle add protocol-hpack
+```
+
+Or install it yourself as:
+
+``` shell
+$ gem install protocol-hpack
+```
+
+## Core Concepts
+
+The `protocol-hpack` gem provides a {ruby Protocol::HPACK::Compressor} and {ruby Protocol::HPACK::Decompressor} for HTTP 2 headers, HPACK, as defined by [RFC7541](https://tools.ietf.org/html/rfc7541).
+
+HPACK is a compression format designed specifically for HTTP/2 to reduce header size and improve performance by minimizing overhead. It addresses the redundancy and repetitive nature of HTTP/1.x headers by employing a static table of common header fields and a dynamic table that evolves based on the headers seen in a particular connection. Headers are encoded into a more compact format, using Huffman coding for literal values and indexing to refer to previously transmitted headers. This approach significantly reduces the amount of data transmitted between client and server, especially in contexts where headers are similar or identical across multiple requests and responses. HPACK's design directly tackles the inefficiencies of HTTP/1.x headers, providing a more bandwidth-efficient and faster web experience by optimizing the way headers are transmitted in HTTP/2 connections.
+
+### Compressing Headers
+
+``` ruby
+require 'protocol/hpack'
+
+buffer = String.new.b
+compressor = Protocol::HPACK::Compressor.new(buffer)
+
+compressor.encode([['content-length', '5']])
+=> "\\\x015"
+```
+
+### Decompressing Headers
+
+Reusing `buffer` from above:
+
+``` ruby
+require 'protocol/hpack'
+
+# Buffer from above...
+buffer = "\\\x015"
+decompressor = Protocol::HPACK::Decompressor.new(buffer)
+
+decompressor.decode
+=> [["content-length", "5"]]
+```
diff --git a/guides/links.yaml b/guides/links.yaml
new file mode 100644
index 0000000..7f527b0
--- /dev/null
+++ b/guides/links.yaml
@@ -0,0 +1,2 @@
+getting-started:
+  order: 1
diff --git a/protocol-hpack.gemspec b/protocol-hpack.gemspec
index 7e55dfd..d592d18 100644
--- a/protocol-hpack.gemspec
+++ b/protocol-hpack.gemspec
@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
 	spec.name = "protocol-hpack"
 	spec.version = Protocol::HPACK::VERSION
 	
-	spec.summary = "A compresssor and decompressor for HTTP 2.0 HPACK."
+	spec.summary = "A compresssor and decompressor for HTTP/2's HPACK format."
 	spec.authors = ["Samuel Williams", "Ilya Grigorik", "Tamir Duberstein", "Kaoru Maeda", "Tiago Cardoso", "Byron Formwalt", "Cyril Roelandt", "Daniel Morrison", "Felix Yan", "George Ulmer", "Jingyi Chen", "Justin Mazzocchi", "Kenichi Nakamura", "Kien Nguyen Trung", "Olle Jonsson"]
 	spec.license = "MIT"
 	
@@ -15,6 +15,10 @@ Gem::Specification.new do |spec|
 	
 	spec.homepage = "https://github.com/socketry/http-hpack"
 	
+	spec.metadata = {
+		"documentation_uri" => "https://socketry.github.io/protocol-hpack/",
+	}
+	
 	spec.files = Dir.glob(['{lib,tasks}/**/*', '*.md'], File::FNM_DOTMATCH, base: __dir__)
 	
 	spec.required_ruby_version = ">= 3.0"
diff --git a/readme.md b/readme.md
index 310d6fe..1907dd0 100644
--- a/readme.md
+++ b/readme.md
@@ -22,32 +22,9 @@ Or install it yourself as:
 
 ## Usage
 
-### Compressing Headers
+Please see the [project documentation](https://socketry.github.io/protocol-hpack/) for more details.
 
-``` ruby
-require 'protocol/hpack'
-
-buffer = String.new.b
-compressor = Protocol::HPACK::Compressor.new(buffer)
-
-compressor.encode([['content-length', '5']])
-=> "\\\x015"
-```
-
-### Decompressing Headers
-
-Reusing `buffer` from above:
-
-``` ruby
-require 'protocol/hpack'
-
-# Buffer from above...
-buffer = "\\\x015"
-decompressor = Protocol::HPACK::Decompressor.new(buffer)
-
-decompressor.decode
-=> [["content-length", "5"]]
-```
+  - [Getting Started](https://socketry.github.io/protocol-hpack/guides/getting-started/index) - This guide explains how to use the `protocol-hpack` gem to compress and decompress HTTP/2 headers using HPACK.
 
 ## Contributing