doc: add fn docstrings and re-org files

src/clj/upwebsite/server.clj

@@ -1,11 +1,27 @@
 (ns upwebsite.server
-  (:require [ring.adapter.jetty :refer [run-jetty]]
+  (:require [optimus.optimizations :as optimizations]
+            [optimus.prime :as optimus]
+            [optimus.strategies :refer [serve-live-assets serve-frozen-assets]]
+            [ring.adapter.jetty :refer [run-jetty]]
             [ring.middleware.reload :refer [wrap-reload]]
+            [stasis.core :as stasis]
             [taoensso.timbre :as log]
-            [upwebsite.web :refer [dev-app prod-app]]))
+            [upwebsite.web :refer [get-pages get-assets]]))
 
 (defonce server (atom nil))
 
+(def dev-app
+  (-> (stasis/serve-pages get-pages)
+      (optimus/wrap get-assets
+                    optimizations/none
+                    serve-live-assets)))
+
+(def prod-app
+  (-> (stasis/serve-pages get-pages)
+      (optimus/wrap get-assets
+                    optimizations/all
+                    serve-frozen-assets)))
+
 (defn start-server! [& [port mode]]
   (log/debug "Mode: " mode)
   (reset! server

src/clj/upwebsite/web.clj

@@ -2,51 +2,57 @@
   (:require [clojure.string :as str]
             [markdown.core :as md]
             [optimus.assets :as assets]
-            [optimus.optimizations :as optimizations]
-            [optimus.prime :as optimus]
-            [optimus.strategies :refer [serve-live-assets]]
             [stasis.core :as stasis]
             [upwebsite.highlight :refer [highlight-code-blocks]]
             [upwebsite.layout :as layout]))
 
-(defn get-assets []
+(defn get-assets
+  "Pick up all files under resources/public/ for optimization"
+  []
   (assets/load-assets "public" [#".*"]))
 
-(defn partial-pages [pages]
+(defn partial-pages
+  "Given a map of url->pages likely from resources/partials/, create a new map
+  of url->(layout/layout-page req page) partial functions."
+  [pages]
   (zipmap (keys pages)
           (map #(fn [req] (layout/layout-page req %)) (vals pages))))
 
-(defn markdown-pages [pages]
+(defn markdown-pages
+  "Given a map of url->pages likely from resources/md/, create a new map
+  of url->(layout/layout-page req page) partial functions,
+  where url is renamed from .md to .html and Markdown is converted to html."
+  [pages]
   (zipmap (map #(str/replace % #"\.md$" ".html") (keys pages))
           (map #(fn [req] (layout/layout-page req (md/md-to-html-string %)))
                (vals pages))))
 
-(defn get-raw-pages []
+(defn get-raw-pages
+  "Merge the various types of pages into a single map of url->pages.
+  Pages may be either strings (raw text) or a function (i.e. (layout-page)).
+  Note: the map is used to label the type of pages for debugging/logging."
+  []
   (stasis/merge-page-sources
    {:public (stasis/slurp-directory "resources/public" #".*\.(html|css|js)$")
     :partials (partial-pages (stasis/slurp-directory "resources/partials" #".*\.html$"))
     :markdown (markdown-pages (stasis/slurp-directory "resources/md" #".*\.md$"))}))
 
 (defn prepare-page
-  "From a URL:page pair and request, create the page (if not a string) and post-process."
+  "From a url:page pair and request, create the page (if not a string) and post-process."
   [[url page] req]
-  (let [prep-page (if (string? page) page (page req))] ;; page is string or fn
+  (let [prep-page (if (string? page) page (page req))] ;; page is string or call page fn
     (if (str/ends-with? url ".html")
       (highlight-code-blocks prep-page)
       prep-page)))
 
 (defn prepare-pages
-  "Create a map of URLs -> (pepare-page page) functions from map of URL -> raw pages."
+  "Create a map of url->(pepare-page page) function from map of url->raw pages."
   [pages]
   (zipmap (keys pages)
           (map #(partial prepare-page %) pages)))
 
-(defn get-pages []
+(defn get-pages
+  "Main function to generate a map of url->page fn (without optimizations)
+  for use by either http server or export code."
+  []
   (prepare-pages (get-raw-pages)))
-
-(def app (-> (stasis/serve-pages get-pages)
-             (optimus/wrap get-assets optimizations/all serve-live-assets)))
-
-(def dev-app app)
-
-(def prod-app app)