Add basic docs website

raiguard · raiguard · commit eeada431a4fd · 2023-03-11T12:04:50.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,7 @@
 .vscode
 ./*.code-workspace
 *.code-workspace
-flib-docs/
+doc-html/
 NOTES.txt
 workspace.html
 faketorio
diff --git a/bounding-box.lua b/bounding-box.lua
@@ -3,6 +3,9 @@ local position = require("__flib__/position")
 --- Utilities for manipulating bounding boxes. All functions support both the shorthand and explicit syntaxes for boxes
 --- and positions, and will preserve the syntax that was passed in. Boxes are considered immutable; all functions will
 --- return new boxes.
+--- ```lua
+--- local flib_bounding_box = require("__flib__/bounding-box")
+--- ```
 --- @class flib_bounding_box
 local flib_bounding_box = {}
 
diff --git a/data-util.lua b/data-util.lua
@@ -1,4 +1,7 @@
 --- Utilities for data stage prototype manipulation.
+--- ```lua
+--- local flib_data_util = require("__flib__/data-util")
+--- ```
 --- @class flib_data_util
 local flib_data_util = {}
 
diff --git a/dictionary-lite.lua b/dictionary-lite.lua
@@ -3,6 +3,9 @@ local mod_gui = require("__core__/lualib/mod-gui")
 local table = require("__flib__/table")
 
 --- Utilities for creating dictionaries of localised string translations.
+--- ```lua
+--- local flib_dictionary = require("__flib__/dictionary-lite")
+--- ```
 --- @class flib_dictionary
 local flib_dictionary = {}
 
diff --git a/direction.lua b/direction.lua
@@ -1,6 +1,9 @@
 local flib_math = require("__flib__/math")
 
 --- Functions for working with directions.
+--- ```lua
+--- local flib_direction = require("__flib__/direction")
+--- ```
 --- @class flib_direction
 local flib_direction = {}
 
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <link rel="stylesheet" href="style.css">
+        <title>flib documentation</title>
+    </head>
+    <body>
+        <h1>Factorio Library documentation</h1>
+        <p>This documentation is auto-generated by the Lua language server.
+        These docs are greatly unpolished and lack any quality of life features
+        whatsoever. This site will be replaced with a custom implementation in the
+        future.</p>
+        <nav>
+            <a href="https://github.com/factoriolib/flib">GitHub</a>
+            <a href="https://mods.factorio.com/mod/flib">Mod portal</a>
+        </nav>
+        {{docs}}
+    </body>
+</html>
diff --git a/docs/style.css b/docs/style.css
@@ -0,0 +1,40 @@
+title { display: none }
+
+body {
+    background-color: #282828;
+    color: #fff;
+    font-family: sans-serif;
+    margin: 0 auto;
+    max-width: 1200px;
+    padding: 1rem;
+    width: auto;
+}
+
+h1 {
+    font-size: 1.5rem;
+    color: #ffe6c0;
+}
+
+h2 {
+    font-size: 1.2rem;
+}
+
+h3 {
+    font-size: 1rem;
+    font-weight: 800;
+}
+
+pre {
+    background-color: #353535;
+    padding: 0.5rem;
+    overflow: scroll;
+    font-family: monospace;
+}
+
+a {
+    color: #ff9f1c;
+}
+
+nav a {
+    margin: 0 1rem;
+}
diff --git a/format.lua b/format.lua
@@ -1,4 +1,7 @@
 --- Various string formatting functions.
+--- ```lua
+--- local flib_format = require("__flib__/format")
+--- ```
 --- @class flib_format
 local flib_format = {}
 
diff --git a/gen-docs.sh b/gen-docs.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+set -e
+
+if [ -d doc-html ]; then
+    rm -rf doc-html
+fi
+mkdir doc-html
+
+docs=$(cmark < $(lua-language-server --doc=. | awk -F ] '/Markdown/ { print $1 }' | awk '{ print substr($2, 2, length($2)) }'))
+cat docs/index.html \
+    | awk -v docs="$docs" '
+        { flag = 1 }
+        /{{docs}}/ { flag = 0; print docs }
+        flag { print }
+    ' > doc-html/index.html
+cp docs/style.css doc-html/style.css
diff --git a/gui-lite.lua b/gui-lite.lua
@@ -1,4 +1,7 @@
 --- Utilities for building GUIs and handling GUI events.
+--- ```lua
+--- local flib_gui = require("__flib__/gui-lite")
+--- ```
 --- @class flib_gui
 local flib_gui = {}
 
diff --git a/math.lua b/math.lua
@@ -1,4 +1,7 @@
 --- Extension of the Lua 5.2 math library.
+--- ```lua
+--- local flib_math = require("__flib__/math")
+--- ```
 --- @class flib_math: factorio.mathlib
 local flib_math = {}
 
diff --git a/migration.lua b/migration.lua
@@ -1,4 +1,7 @@
 --- Mod migration and version comparison functions.
+--- ```lua
+--- local flib_migration = require("__flib__/migration")
+--- ```
 --- @class flib_migration
 local flib_migration = {}
 
@@ -10,7 +13,7 @@ local version_format = "%02d"
 
 --- Normalize version strings for easy comparison.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- migration.format_version("1.10.1234", "%04d")
@@ -67,7 +70,7 @@ end
 
 --- Determine if migrations need to be run for this mod, then run them if needed.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- script.on_configuration_changed(function(e)
diff --git a/on-tick-n.lua b/on-tick-n.lua
@@ -1,4 +1,7 @@
 --- Schedule tasks to be executed later.
+--- ```lua
+--- local flib_on_tick_n = require("__flib__/on-tick-n")
+--- ```
 --- @class flib_on_tick_n
 local on_tick_n = {}
 
diff --git a/orientation.lua b/orientation.lua
@@ -1,4 +1,7 @@
 --- Functions for working with orientations.
+--- ```lua
+--- local flib_orientation = require("__flib__/orientation")
+--- ```
 --- @class flib_orientation
 local flib_orientation = {}
 
diff --git a/position.lua b/position.lua
@@ -1,5 +1,8 @@
 --- Utilities for manipulating positions. All functions support both the shorthand and explicit syntaxes and will
 --- preserve the syntax that was passed in.
+--- ```lua
+--- local flib_position = require("__flib__/position")
+--- ```
 --- @class flib_position
 local flib_position = {}
 
diff --git a/queue.lua b/queue.lua
@@ -1,6 +1,9 @@
 --- Lua queue implementation.
 ---
 --- Based on "Queues and Double Queues" from [Programming in Lua](http://www.lua.org/pil/11.4.html).
+--- ```lua
+--- local flib_queue = require("__flib__/queue")
+--- ```
 --- @class flib_queue
 local flib_queue = {}
 
diff --git a/table.lua b/table.lua
@@ -3,6 +3,9 @@
 --- **NOTE:** Several functions in this module will only work with [arrays](https://www.lua.org/pil/11.1.html),
 --- which are tables with sequentially numbered keys. All table functions will work with arrays as well, but
 --- array functions **will not** work with tables.
+--- ```lua
+--- local flib_table: = require("__flib__/table")
+--- ```
 --- @class flib_table: tablelib
 local flib_table = {}
 
@@ -105,7 +108,7 @@ end
 ---
 --- Non-merged tables are deep-copied, so the result is brand-new.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {foo = "bar"}
@@ -137,7 +140,7 @@ end
 
 --- Find and return the first key containing the given value.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {"foo", "bar"}
@@ -160,7 +163,7 @@ end
 ---
 --- Calls `callback(value, key)` for each item in the table, and immediately ceases iteration if the callback returns truthy.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {1, 2, 3, 4, 5}
@@ -200,7 +203,7 @@ end
 --- **DO NOT** delete entires from `tbl` from within `callback`, this will break the iteration. Use the deletion flag
 --- instead.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local extremely_large_table = {
@@ -280,7 +283,7 @@ end
 --- Calls `filter(value, key)` on each element in the table, returning a new table with only pairs for which
 --- `filter` returned a truthy value.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {1, 2, 3, 4, 5, 6}
@@ -327,7 +330,7 @@ end
 ---
 --- Non-unique values are overwritten based on the ordering from `pairs()`.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {"foo", "bar", "baz", set = "baz"}
@@ -348,7 +351,7 @@ end
 ---
 --- Calls `mapper(value, key)` on each element in the table, using the return as the new value for the key.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {1, 2, 3, 4, 5}
@@ -406,7 +409,7 @@ end
 ---
 --- Calls `reducer(accumulator, value, key)` on each element in the table, returning a single accumulated output value.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local tbl = {10, 20, 30, 40, 50}
@@ -479,7 +482,7 @@ flib_table.size = _ENV.table_size
 ---
 --- The original array **will not** be modified.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local arr = {10, 20, 30, 40, 50, 60, 70, 80, 90}
@@ -515,7 +518,7 @@ end
 --
 --- The original array **will** be modified.
 ---
---- # Examples
+--- ### Examples
 ---
 --- ```lua
 --- local arr = {10, 20, 30, 40, 50, 60, 70, 80, 90}
diff --git a/train.lua b/train.lua
@@ -1,4 +1,7 @@
 --- Functions for working with trains.
+--- ```lua
+--- local flib_train = require("__flib__/train")
+--- ```
 --- @class flib_train
 local flib_train = {}
 
