add basic How it Works docs (#2239)

* add basic How it Works docs

* edits

* lints

* clarify initialization lifecyle section

Author: joelhawksley

docs/CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Changelog
-nav_order: 5
+nav_order: 6
 ---
 
 <!-- Add unreleased changes under the "main" heading. -->
@@ -10,6 +10,10 @@ nav_order: 5
 
 ## main
 
+* Add documentation on how ViewComponent works.
+
+    *Joel Hawksley*
+
 ## 3.22.0
 
 * Rewrite `ViewComponents at GitHub` documentation as more general `Best practices`.

docs/CODE_OF_CONDUCT.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Code of conduct
-nav_order: 6
+nav_order: 7
 ---
 
 # Contributor Covenant Code of Conduct

docs/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Contributing
-nav_order: 7
+nav_order: 9
 ---
 
 # Contributing

docs/compatibility.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Compatibility
-nav_order: 6
+nav_order: 8
 ---
 
 # Compatibility

docs/history.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: History
-nav_order: 8
+nav_order: 10
 ---
 
 # History

docs/how-it-works.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: How it works
+nav_order: 5
+---
+
+## How ViewComponent Works
+
+### At application boot
+
+When `ViewComponent::Base` is inherited from, `ViewComponent::Compiler.compile` compiles a component's template(s) into instance method(s) on the component:
+
+```ruby
+class MyComponent < ViewComponent::Base
+end
+```
+
+```erb
+<%= Time.now %>
+```
+
+Compiles to:
+
+```ruby
+class MyComponent < ViewComponent::Base
+  def _call_my_component
+    @output_buffer.append = (Time.now)
+    @output_buffer
+  end
+end
+```
+
+### At component instantiation
+
+Component initializer runs if defined. ViewComponent does not perform any actions.
+
+### At render
+
+When a ViewComponent is passed to `render`, Rails calls `render_in`, passing the current [ActionView::Context](https://api.rubyonrails.org/classes/ActionView/Context.html). `ActionView::Context` is used to provide access to the current controller, request, and helpers, which is why they cannot be referenced until a component is rendered.
+
+First, ViewComponent calls the `before_render` method, which gives ViewComponents the opportunity to execute logic before render time but after initialization.
+
+Second, ViewComponent calls `render?`, returning early with an empty string if `render?` returns false.
+
+ViewComponent then renders the component template.

docs/known_issues.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Known issues
-nav_order: 9
+nav_order: 11
 ---
 
 # Known issues

docs/logo.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Logo
-nav_order: 11
+nav_order: 12
 ---
 
 # Logo

docs/resources.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Resources
-nav_order: 12
+nav_order: 13
 ---
 
 # Resources