docs: lot more docs

Author: mhanberg

lib/tableau.ex

@@ -1,7 +1,28 @@
 defmodule Tableau do
-  @moduledoc false
+  @moduledoc """
+  ## Global Site Configuration
+
+  * `:include_dir` - string - Directory that is just copied to the output directory. Defaults to `extra`.
+  * `:timezone` - string - Timezone to use when parsing date times. Defaults to `Etc/UTC`.
+  * `:url` - string (required) - The URL of your website.
+  * `:markdown` - keyword
+      * `:mdex` - keyword - Options to pass to `MDEx.to_html/2`
+  """
+
+  @doc """
+  Component to connect to the development server via websocket to broadcast that the page should reload.
+
+  By default, connects to `'ws://' + location.host + '/ws'`.
+
+  See `WebDevUtils` for configuration options.
+  """
   defdelegate live_reload(assigns), to: WebDevUtils.Components
 
+  @doc """
+  Convert markdown content to HTML using `MDEx.to_html/2`.
+
+  Will use the globally configured options, but you can also pass it overrides.
+  """
   def markdown(content, overrides \\ []) do
     {:ok, config} = Tableau.Config.new(Map.new(Application.get_env(:tableau, :config, %{})))
 

lib/tableau/config.ex

@@ -1,13 +1,5 @@
 defmodule Tableau.Config do
-  @moduledoc """
-  Project configuration.
-
-  * `:include_dir` - Directory that is just copied to the output directory. Defaults to `extra`.
-  * `:timezone` - Timezone to use when parsing date times. Defaults to `Etc/UTC`.
-  * `:url` - The URL of your website.
-  * `:markdown` - keyword
-      * `:mdex` - keyword - Options to pass to [MDEx](https://hexdocs.pm/mdex/MDEx.html#to_html/2)
-  """
+  @moduledoc false
 
   import Schematic
 

lib/tableau/extension.ex

@@ -16,7 +16,7 @@ defmodule Tableau.Extension do
   There are currently the following extension types:
 
   - `:pre_build` - executed before tableau builds your site and writes anything to disk.
-  - `:post_write` - executed after tableau builds your site and writes everthing to disk.
+  - `:post_write` - executed after tableau builds your site and writes everything to disk.
 
   ## Example
 
@@ -40,13 +40,14 @@ defmodule Tableau.Extension do
   '''
 
   @typep extension_type :: :pre_build | :post_write
+  @type token :: map()
 
   @doc """
   The extension entry point.
 
   The function is passed a token and can return a new token with new data loaded into it.
   """
-  @callback run(map()) :: {:ok, map()} | :error
+  @callback run(token()) :: {:ok, token()} | :error
 
   defmacro __using__(opts) do
     opts = Keyword.validate!(opts, [:key, :enabled, :type, :priority])

lib/tableau/extensions/data_extension.ex

@@ -17,6 +17,10 @@ defmodule Tableau.DataExtension do
     dir: "_facts"
   ```
 
+  <!-- tabs-open -->
+
+  ### YAML
+
   ```yaml
   # _facts/homies.yaml
   - name: Mitch
@@ -32,6 +36,24 @@ defmodule Tableau.DataExtension do
   </ul>
   ```
 
+  ### Elixir
+
+  ```elixir
+  # _facts/homies.exs
+  resp = Req.get!("https://example.com/homies")
+
+  resp.body["homies"]
+  ```
+
+  ```heex
+  <ul>
+    <li :for={homie <- @data["homies"]}>
+      <%= homie.name %>
+    </li>
+  </ul>
+  ```
+
+  <!-- tabs-close -->
   """
   use Tableau.Extension, key: :data, type: :pre_build, priority: 200
 

mix.exs

@@ -13,7 +13,8 @@ defmodule Tableau.MixProject do
       elixirc_paths: elixirc_paths(Mix.env()),
       start_permanent: Mix.env() == :prod,
       package: package(),
-      deps: deps()
+      deps: deps(),
+      docs: docs()
     ]
   end
 
@@ -61,4 +62,24 @@ defmodule Tableau.MixProject do
       files: ~w(lib LICENSE mix.exs README.md .formatter.exs)
     ]
   end
+
+  defp docs do
+    [
+      main: "Tableau",
+      groups_for_modules: [
+        Site: [
+          Tableau,
+          Tableau.Layout,
+          Tableau.Page,
+          Tableau.Document.Helper
+        ],
+        Extensions: [
+          Tableau.Extension,
+          Tableau.PostExtension,
+          Tableau.RSSExtension,
+          Tableau.DataExtension
+        ]
+      ]
+    ]
+  end
 end

mix.lock

@@ -2,15 +2,15 @@
   "bandit": {:hex, :bandit, "1.0.0", "2bd87bbf713d0eed0090f2fa162cd1676198122e6c2b68a201c706e354a6d5e5", [:mix], [{:hpax, "~> 0.1.1", [hex: :hpax, repo: "hexpm", optional: false]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:thousand_island, "~> 1.0", [hex: :thousand_island, repo: "hexpm", optional: false]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "32acf6ac030fee1f99fd9c3fcf81671911ae8637e0a61c98111861b466efafdb"},
   "castore": {:hex, :castore, "1.0.4", "ff4d0fb2e6411c0479b1d965a814ea6d00e51eb2f58697446e9c41a97d940b28", [:mix], [], "hexpm", "9418c1b8144e11656f0be99943db4caf04612e3eaecefb5dae9a2a87565584f8"},
   "earmark": {:hex, :earmark, "1.4.46", "8c7287bd3137e99d26ae4643e5b7ef2129a260e3dcf41f251750cb4563c8fb81", [:mix], [], "hexpm", "798d86db3d79964e759ddc0c077d5eb254968ed426399fbf5a62de2b5ff8910a"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.32", "fa739a0ecfa34493de19426681b23f6814573faee95dfd4b4aafe15a7b5b32c6", [:mix], [], "hexpm", "b8b0dd77d60373e77a3d7e8afa598f325e49e8663a51bcc2b88ef41838cca755"},
-  "ex_doc": {:hex, :ex_doc, "0.29.4", "6257ecbb20c7396b1fe5accd55b7b0d23f44b6aa18017b415cb4c2b91d997729", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "2c6699a737ae46cb61e4ed012af931b57b699643b24dabe2400a8168414bc4f5"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.37", "2ad73550e27c8946648b06905a57e4d454e4d7229c2dafa72a0348c99d8be5f7", [:mix], [], "hexpm", "6b19783f2802f039806f375610faa22da130b8edc21209d0bff47918bb48360e"},
+  "ex_doc": {:hex, :ex_doc, "0.30.9", "d691453495c47434c0f2052b08dd91cc32bc4e1a218f86884563448ee2502dd2", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "d7aaaf21e95dc5cddabf89063327e96867d00013963eadf2c6ad135506a8bc10"},
   "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "floki": {:hex, :floki, "0.34.3", "5e2dcaec5d7c228ce5b1d3501502e308b2d79eb655e4191751a1fe491c37feac", [:mix], [], "hexpm", "9577440eea5b97924b4bf3c7ea55f7b8b6dce589f9b28b096cc294a8dc342341"},
   "hpax": {:hex, :hpax, "0.1.2", "09a75600d9d8bbd064cdd741f21fc06fc1f4cf3d0fcc335e5aa19be1a7235c84", [:mix], [], "hexpm", "2c87843d5a23f5f16748ebe77969880e29809580efdaccd615cd3bed628a8c13"},
   "libgraph": {:hex, :libgraph, "0.16.0", "3936f3eca6ef826e08880230f806bfea13193e49bf153f93edcf0239d4fd1d07", [:mix], [], "hexpm", "41ca92240e8a4138c30a7e06466acc709b0cbb795c643e9e17174a178982d6bf"},
   "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
   "mdex": {:hex, :mdex, "0.1.11", "83bac0b339811310362c86087c1ea1d37cf3190f41993a7de41fea81ccdbc8a1", [:mix], [{:rustler, "~> 0.29", [hex: :rustler, repo: "hexpm", optional: true]}, {:rustler_precompiled, "~> 0.6", [hex: :rustler_precompiled, repo: "hexpm", optional: false]}], "hexpm", "303510829f3c59295e13b27992ef542356db8276a3a514f1369ae91afb62f60b"},
   "mime": {:hex, :mime, "2.0.5", "dc34c8efd439abe6ae0343edbb8556f4d63f178594894720607772a041b04b02", [:mix], [], "hexpm", "da0d64a365c45bc9935cc5c8a7fc5e49a0e0f9932a761c55d6c52b142780a05c"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"},