Clean up API reference, rewrap examples, add requirements.txt

docs/api-reference.md

@@ -2,60 +2,87 @@
 
 ## Objects
 
-### `Roact.Component`
+### Roact.Component
 The base component instance that can be extended to make stateful components.
 
 Call `Roact.Component:extend("ComponentName")` to make a new stateful component with a given name.
 
-### `Roact.PureComponent`
+### Roact.PureComponent
 An extension of `Roact.Component` that only re-renders if its props or state change.
 
 `PureComponent` implements `shouldUpdate` with a sane default. It's possible that `PureComponent` could be slower than doing a wasteful re-render, so measure!
 
 ## Constants
 
-### `Roact.Children`
+### Roact.Children
 This is the key that Roact uses internally to store the children that are attached to a Roact element.
 
 If you're writing a new functional or stateful element that needs to be used like a primitive component, you can access `Roact.Children` in your props table.
 
-### `Roact.Ref`
+### Roact.Ref
 Used to access underlying Roblox instances. See [the refs example](/examples/refs.html) for more details.
 
-### `Roact.Event`
+### Roact.Event
 Index into this object to get handles that can be used for attaching events to Roblox objects. See [the events example](/examples/events.md) for more details.
 
 ## Methods
 
-### `Roact.createElement(component, [props, [children]]) -> RoactElement`
-Creates a new Roact element representing the given `component`.
+### Roact.createElement
+```
+Roact.createElement(component, [props, [children]]) -> RoactElement
+```
 
-Once `props` or `children` are passed into the `createElement` function, it's important that those tables aren't mutated.
+Creates a new Roact element representing the given `component`.
 
 The `children` argument is shorthand for adding a `Roact.Children` key to `props`. It should be specified as a dictionary of names to elements.
 
 `component` can be a string, a function, or a table created by `Component:extend`.
 
-### `Roact.reify(element, [parent, [key]]) -> RoactComponentInstance`
+!!! caution
+	Once `props` or `children` are passed into the `createElement`, make sure not to modify them!
+
+### Roact.reify
+```
+Roact.reify(element, [parent, [key]]) -> RoactComponentInstance
+```
+
 Creates a Roblox Instance given a Roact element, and optionally a `parent` to put it in, and a `key` to use as the instance's `Name`.
 
 The result is a `RoactComponentInstance`, which is an opaque handle that represents this specific instance of the root component. You can pass this to APIs like `Roact.teardown` and the future debug API.
 
-### `Roact.teardown(instance)`
+### Roact.teardown
+```
+Roact.teardown(instance)
+```
+
 Destroys the given `RoactComponentInstance` and all of its descendents. Does not operate on a Roblox Instance -- this must be given a handle that was returned by `Roact.reify`.
 
-### `Roact.oneChild(children) -> RoactElement | nil`
+### Roact.oneChild
+`Roact.oneChild(children) -> RoactElement | nil`
+
 Given a dictionary of children, returns a single child element.
 
 If `children` contains more than one child, `oneChild` function will throw an error. This is intended to denote an error when using the component using `oneChild`.
 
 If `children` is `nil` or contains no children, `oneChild` will return `nil`.
 
-### `Roact.isPrimitveElement(element) -> bool`
+### Roact.isPrimitiveElement
+```
+Roact.isPrimitveElement(element) -> bool
+```
+
 Determines whether the given `element` is primtive. These elements are created with a string parameter to `createElement` and represent a Roblox instance.
 
-### `Roact.isFunctionalElement(element) -> bool`
+### Roact.isFunctionalElement
+```
+Roact.isFunctionalElement(element) -> bool
+```
+
 Determines whether the given `element` is functional. These elements are created with a function parameter to `createElement` and represent a stateless Roact component.
 
-### `Roact.isStatefulElement(element) -> bool`
+### Roact.isStatefulElement
+```
+Roact.isStatefulElement(element) -> bool
+```
+
 Determines whether the given `element` is stateful. These elements are created with a table parameter to `createElement` and represent a *potentially* stateful Roact component.

docs/examples/hello-roact.md

@@ -12,8 +12,8 @@ local function HelloComponent()
 	--[[
 		createElement takes three arguments:
 			* The component that this element represents
-			* Optionally, a list of properties to provide
-			* Optionally, a dictionary of children -- the key is that child's Name
+			* Optional: a list of properties to provide
+			* Optional: a dictionary of children -- the key is that child's Name
 	]]
 
 	return Roact.createElement("ScreenGui", {
@@ -29,7 +29,8 @@ end
 local element = Roact.createElement(HelloComponent)
 
 --[[
-	`reify` turns our virtual tree into real instances and puts the top-most one in PlayerGui
+	`reify` turns our virtual tree into real instances and puts the top-most one
+	in PlayerGui
 
 	reify takes three arguments:
 		* The element we're trying to reify

docs/examples/refs.md

@@ -19,7 +19,8 @@ local currentFrame
 local element = Roact.createElement("Frame", {
 	-- Use Roact.Ref as the key to attach a ref, just like events.
 	[Roact.Ref] = function(rbx)
-		-- All properties are already set and the object has been parented at this point.
+		-- All properties are already set and the object has been parented at
+		-- this point.
 		currentFrame = rbx
 	end
 })

docs/examples/roact-rodux.md

@@ -11,7 +11,8 @@ local RoactRodux = require(ReplicatedStorage.RoactRodux)
 
 -- Roact Portion
 -- This code doesn't know anything about Rodux.
--- It can function as an isolated component -- components designed this way are often cleaner!
+-- It can function as an isolated component -- components designed this way are
+-- often cleaner!
 local App = Roact.Component:extend("App")
 
 function App:render()
@@ -68,8 +69,8 @@ end
 
 local store = Rodux.Store.new(reducer)
 
--- We wrap our Roact-Rodux app in a `StoreProvider`, which makes sure our components know
--- what store they should be connecting to.
+-- We wrap our Roact-Rodux app in a `StoreProvider`, which makes sure our
+-- components know what store they should be connecting to.
 local app = Roact.createElement(RoactRodux.StoreProvider, {
 	store = store,
 }, {

mkdocs.yml

@@ -7,7 +7,7 @@ theme:
 
 pages:
   - Home: index.md
-  - 'What is Roact?': what-is-roact.md
+  - What is Roact?: what-is-roact.md
   - Getting Started: getting-started.md
   - Guide:
     - Elements and Components: guide/elements-components.md
@@ -16,9 +16,14 @@ pages:
     - Usage with Rodux: guide/usage-with-rodux.md
   - API Reference: api-reference.md
   - Examples:
-    - Hello, Roact: examples/hello-roact.md
+    - Hello, Roact!: examples/hello-roact.md
     - Stateful Counter: examples/counter.md
     - Events, the Roact Way: examples/events.md
     - Tearing Down Components: examples/teardown.md
     - Refs: examples/refs.md
-    - Roact with Rodux: examples/roact-rodux.md
+    - Roact with Rodux: examples/roact-rodux.md
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      guess_lang: false

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+pymdown-extensions