Documentation

Makefile

@@ -9,6 +9,7 @@ CD=cd
 AWK=awk
 GREP=grep
 SORT=sort
+TEST=test
 
 # Config
 worker_chroot = $(smr_var)/kore_worker
@@ -104,13 +105,13 @@ install: $(app_root) $(kmgr_chroot) $(parent_chroot) $(initscript) $(config) smr
 
 $(config) : conf/smr.conf
 	$(Q)$(MKDIR) $(conf_path)
-	$(Q)$(COPY) $< $@
+	$(Q)$(TEST) ! -e $@ && $(COPY) $< $@
 
 $(initscript) : packaging/systemd/smr.service
 	$(Q)$(COPY) $< $@
 
 cloc: ## calculate source lines of code in smr
-	cloc --force-lang="html",etlua --force-lang="lua",luasrc assets Makefile
+	cloc --force-lang="html",etlua --force-lang="lua",lua src assets Makefile
 
 $(app_root):
 	$(Q)$(MKDIR) $(app_root)
@@ -153,7 +154,7 @@ $(built_sql): $(app_root)/sql/%.sql : src/sql/%.sql
 	$(Q)$(ECHO) "[copy] $@"
 	$(Q)$(COPY) $^ $@
 
-$(built_tests) : $(app_root)/spec/% : spec/% $(app_root)/spec
+$(built_tests): $(app_root)/spec/% : spec/% $(app_root)/spec
 	$(Q)$(ECHO) "[copy] $@"
 	$(Q)$(COPY) $< $@
 
@@ -161,15 +162,22 @@ $(app_root)/spec: $(app_root)
 	$(Q)$(MKDIR) $@
 	$(Q)$(MKDIR) $@/parser_tests
 
-smr.so : $(src_files) conf/build.conf $(asset_files)
+smr.so: $(src_files) conf/build.conf $(asset_files)
 	$(Q)$(ECHO) "[build] $@"
 	$(Q)$(KODEV) build
 
-test : $(built) ## run the unit tests
+test: $(built) ## run the unit tests
 	$(Q)$(CD) $(app_root) && busted -v --no-keep-going --exclude-tags "slow,todo,working"
 
-cov : $(built) ## code coverage (based on unit tests)
+cov: $(built) ## code coverage (based on unit tests)
 	$(Q)$(RM) $(kore_chroot)/luacov.stats.out
 	$(Q)$(CD) $(kore_chroot) && busted -v -c --no-keep-going --exclude-tags slow
 	$(Q)$(CD) $(kore_chroot) && luacov endpoints/
 	$(Q)$(ECHO) "open kore_chroot/luacov.report.out to view coverage results."
+
+doc: 
+	rm -rf .trblcache
+	~/Programs/trbldoc/trbldoc.sh src
+	cd .trblcache/built && python3 -m http.server
+
+.PHONY: doc

doc/appendix.md

@@ -6,3 +6,4 @@ All other values are considered truethy.
 In addition, tables may have a metatable that has a `__toboolean` function
 to implement their own truethyness or falseyness. `false` should be used in
 places where a boolean is expected, and `nil` should be used otherwise.
+

doc/hooks.md

@@ -12,3 +12,9 @@ create_user(details :: table) :: boolean
 ```
 Called when a user creates a user account on the site.
 
+```
+authenticate(data :: table) :: number | nil, string
+```
+Called when a user attempts to log in. Return a number, userid if the login is successful, or nil and an error message if the login is not successful. By default, smr puts "user" and "passfile" fields into the data table.
+
+

src/lua/addon.lua

@@ -1,6 +1,12 @@
 --[[ md
 @name lua/addon
 
+## Addon
+
+Addons allow you to modify the behavior of smr without modifying the smr
+source code. This is intended to make updates easier, and to modularize parts
+of smr that are not minimally required.
+
 Addon loader - Addons are either:
 * A folder with at least two files:
   - meta.lua - contains addon information
@@ -9,8 +15,10 @@ Addon loader - Addons are either:
 * A sqlite3 database with a table "files" that has at least the columns
   * name :: TEXT - The filename
   * data :: BINARY - The file data
-  And there are at least 2 rows with filenames `meta.lua` and `init.lua`
-  as described above. Addons should be placed in $SMR_ADDONS, defined in config.lua
+
+And there are at least 2 rows with filenames `meta.lua` and `init.lua`
+as described above. Addons should be placed in {{config/addons_folder},
+defined in `config.lua`
 
 The `meta.lua` file is run at worker init time (i.e. it will be run once for
 each worker), and should return a table with at least the following information

src/lua/hooks.lua

@@ -1,13 +1,47 @@
---[[
+--[[ md
+@name lua/hooks
+
 Global functions that smr exposes that can be detoured by addons
+
+]]
+
+--[[ md
+@name doc/detouring
+
+# Detouring
+
+In Lua, functions are given a name, but more generally, they values on a table
+, perhaps the global table `_G`, and their names are the keys on the table.
+When you want to modify a function that exists either in smr or in other addons
+you can **detour** the function by saving a reference to the original function,
+and then creating a new function that calls the original, maybe after doing
+other work, or modifying the arguments. For example:
+
+	local pages = require("pages")
+
+	-- Get notified when the index page is rendered to the user
+	local oldindex = pages.index
+	function pages.index(...)
+		print("Index page is getting rendered!")
+		oldindex(...)
+	end
 ]]
 
 local api = {}
 
--- Called before any request processing. Returning true "traps" the request, and
--- does not continue calling smr logic. Well-behaved addons should check for
--- "true" from the detoured function, and return true immediately if the check 
--- succeeds.
+--[[ md
+@name lua/hooks
+
+## pre_request
+
+Called before any request processing. Returning true "traps" the request, and
+does not continue calling smr logic. Well-behaved addons should check for
+"true" from the detoured function, and return true immediately if the check 
+succeeds.
+
+@param req {{http_request}} - The request about to be processed
+@returns boolean - If true, further processing is not done on this request.
+]]
 api.pre_request = function(req) end
 
 -- Called after smr request processing. Returning true "traps" the request. 

src/lua/init.lua

@@ -4,6 +4,36 @@ It registers a bunch of global functions that get called from kore when users
 visit particular pages. See src/smr.c for the names of the public functions.
 See conf/smr.conf for the data that can be access in each function
 ]]
+
+--[[ md
+@name lua
+
+# Lua namespace
+
+By default, smr will run init.lua defined by smr, and then addons in order,
+see {{lua/addon}} for information on how smr loads addons. You can use any
+of the modules that ship with smr by including them, and then calling the
+functions defined in that module.
+
+For example, the module {{lua/db}} holdes a reference to the sqlite3 database
+that smr uses for data storage. If you addon needs to set up a table and
+prepare sql statements for an api endpoint, you might set it up like this:
+
+	local db = require("db")
+	
+	local oldconfigure = configure -- Hold a refrence to configure()
+	function configure(...) -- Detour the configure function
+		db.sqlassert(db.conn:exec([=[
+			CREATE TABLE IF NOT EXISTS foo (
+				id INTEGER AUTOINCREMENT PRIMARY KEY
+				value TEXT
+			);
+		]=]))
+		oldconfigure(...)
+	end
+
+Be sure to always {{doc/appendix/detourin}}
+]]
 print("Really fast print from init.lua")
 
 --Luarocks libraries