Add documentation.

fiber-local.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
 	spec.homepage = "https://github.com/socketry/fiber-local"
 
 	spec.metadata = {
+		"documentation_uri" => "https://socketry.github.io/fiber-local/",
 		"source_code_uri" => "https://github.com/socketry/fiber-local.git",
 	}
 

guides/getting-started/readme.md

@@ -0,0 +1,89 @@
+# Getting Started
+
+This guide will explain how and why to use `Fiber::Local` to simplify fiber-local state.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ bundle add fiber-local
+```
+
+## Core Concepts
+
+- {ruby Fiber::Local} is a module which exposes an instance of something as fiber-local state.
+
+## Usage
+
+In your own class, e.g. `Logger`:
+
+``` ruby
+class Logger
+	extend Fiber::Local
+
+	def initialize
+		@buffer = []
+	end
+
+	def log(*arguments)
+		@buffer << arguments
+	end
+end
+```
+
+Now, instead of instantiating your cache `LOGGER = Logger.new`, use `Logger.instance`. It will return a thread-local instance.
+
+``` ruby
+Thread.new do
+	Logger.instance
+	# => #<Logger:0x000055a14ec6be80>
+end
+
+Thread.new do
+	Logger.instance
+	# => #<Logger:0x000055a14ec597d0>
+end
+```
+
+In cases where you have job per fiber or request per fiber, you might want to collect all log output for a specific fiber, you can do the following:
+
+``` ruby
+Logger.instance
+# => #<Logger:0x000055a14ec6be80>
+
+Fiber.new do
+	Logger.instance = Logger.new
+	# => #<Logger:0x000055a14ec597d0>
+end
+```
+
+## Sharing
+
+You can assign to the fiber-local instance which inherited to child fibers and threads.
+
+``` ruby
+Logger.instance
+# => #<Logger:0x000055a14ec6be80>
+
+Fiber.new do
+	Logger.instance = Logger.new
+	# => #<Logger:0x000055a14ec597d0>
+
+	Fiber.new do
+		Logger.instance
+		# => #<Logger:0x000055a14ec597d0>
+	end.resume
+
+	Thread.new do
+		Logger.instance
+		# => #<Logger:0x000055a14ec597d0>
+	end.join
+end.resume
+```
+
+You can use this to control per-request or per-operation state.
+
+### Thread Safety
+
+`Fiber::Local` is thread-safe. It uses a thread-local variable to store the fiber-local instance. However, you must also ensure that the instance you are storing is thread-safe, if you expect to share it across threads.

guides/links.yaml

@@ -0,0 +1,2 @@
+getting-started:
+  order: 1

readme.md

@@ -1,63 +1,14 @@
 # Fiber::Local
 
-A module to simplify fiber-local state.
+A module to simplify fiber-local state. This provides a convenient interface for providing a default per-thread instance, while allowing per-fiber overrides (e.g. per-request state handling).
 
 [![Development Status](https://github.com/socketry/fiber-local/workflows/Test/badge.svg)](https://github.com/socketry/fiber-local/actions?workflow=Test)
 
-## Features
-
-  - Easily access fiber-local state from a fiber.
-  - Default to shared thread-local state.
-
-## Installation
-
-``` bash
-$ bundle add fiber-local
-```
-
 ## Usage
 
-In your own class, e.g. `Logger`:
-
-``` ruby
-class Logger
-	extend Fiber::Local
-
-	def initialize
-		@buffer = []
-	end
-
-	def log(*arguments)
-		@buffer << arguments
-	end
-end
-```
-
-Now, instead of instantiating your cache `LOGGER = Logger.new`, use `Logger.instance`. It will return a thread-local instance.
-
-``` ruby
-Thread.new do
-	Logger.instance
-	# => #<Logger:0x000055a14ec6be80>
-end
-
-Thread.new do
-	Logger.instance
-	# => #<Logger:0x000055a14ec597d0>
-end
-```
-
-In cases where you have job per fiber or request per fiber, you might want to collect all log output for a specific fiber, you can do the following:
-
-``` ruby
-Logger.instance
-# => #<Logger:0x000055a14ec6be80>
+Please see the [project documentation](https://socketry.github.io/fiber-local/) for more details.
 
-Fiber.new do
-	Logger.instance = Logger.new
-	# => #<Logger:0x000055a14ec597d0>
-end
-```
+  - [Getting Started](https://socketry.github.io/fiber-local/guides/getting-started/index) - This guide will explain how and why to use `Fiber::Local` to simplify fiber-local state.
 
 ## Contributing