Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@respatialized
respatialized committed Aug 3, 2024
1 parent 1e4d9d2 commit cf07024
Show file tree
Hide file tree
Showing 3 changed files with 90 additions and 63 deletions.
16 changes: 11 additions & 5 deletions dev/site/fabricate/dev/styles.clj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,16 @@
:font-weight "700"
:content "\"+\""}]
[(select/ins select/after) {:content "\"\"" :display "block"}]]
[:dl {:display "grid" :grid-column-gap "0.5em" :grid-row-gap "0.65em"}
[:dt {:grid-column "1 / 3 !important" :font-weight "600"}]
[:dd {:grid-column "3 !important" :margin-left "0em" :min-width "25ch"}]]
[:dl
[:dl {:display "block"} [:dt {:grid-column "auto"}]
[:dd {:grid-column "auto"}]]]
{:display "grid"
:grid-column-gap "0.5em"
:grid-row-gap "0.65em"
:grid-template-columns "subgrid"}
[:dt {:grid-column "1 / 3" :font-weight "600"}]
[:dd {:grid-column "3 " :margin-left "0em" :min-width "25ch"}]]
#_[:dl
[:dl {:display "block"} [:dt {:grid-column "auto"}]
[:dd {:grid-column "auto"}]]]
(stylesheet/at-media {:max-width "900px"}
[:p :ul :ol {:grid-column "1 / 10"}]
[:div {:grid-column "1 / 13"}]
Expand Down Expand Up @@ -111,6 +115,8 @@
[:.shell
[(select/code select/before) {:position "relative" :content "\"$ \""}]]
[:.small {:font-size "0.75em"}]
[:.fabricate-src {:max-width "85ch"}]
[:.instaparse-grammar {:line-height 1.45}]
#_[:.example-rows
{:display "flex"
:flex-flow "row wrap"
Expand Down
23 changes: 14 additions & 9 deletions pages/reference/namespaces/site.fabricate.prototype.read.grammar.html.fab
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
✳(ns site.fabricate.docs.reference.namespaces.grammar
(:require [site.fabricate.prototype.read.grammar :as grammar]
[instaparse.core :as insta]
[site.fabricate.adorn :as adorn]
[instaparse.print :refer [Parser->str]]
[site.fabricate.prototype.page :as page]
[malli.core :as m]
[garden.core :as garden]
[site.fabricate.dev.styles :as styles])) 🔚
(:require [site.fabricate.prototype.read.grammar :as grammar]
[instaparse.core :as insta]
[site.fabricate.adorn :as adorn]
[instaparse.print :refer [Parser->str]]
[site.fabricate.prototype.page :as page]
[hiccup.util]
[malli.core :as m]
[garden.core :as garden]
[site.fabricate.dev.styles :as styles]
[clojure.string :as str])) 🔚

✳(def metadata {:title "site.fabricate.prototype.read.grammar Namespace"
:page-style (garden/css styles/docs)}) 🔚
Expand All @@ -20,7 +22,10 @@
✳=[:h2 "The grammar definition"]🔚
This ✳=[:a {:href "https://github.com/engelberg/instaparse"} [:code "Instaparse"]]🔚 grammar defines the structure of Fabricate templates. Once parsed into an Instaparse parse tree, the ✳=[:a {:href "/reference/namespaces/site.fabricate.prototype.read.html"} [:code "read"] " namespace"]🔚 walks the parsed template and evaluates the expressions embedded within it. The grammar, as defined, intentionally does not concern itself with whether the contents of the expressions in each template are syntactically valid Clojure forms; that task is left to the reader. Defining the grammar this way allows Clojure read errors to be caught and handled on a form-by-form basis instead of throwing an error for the whole page.

✳=[:pre (Parser->str (var-get ('template vars)))]🔚
✳=[:pre {:class "instaparse-grammar"}
(hiccup.util/escape-html
#_(str/replace )
(Parser->str (var-get ('template vars))))]🔚

For an informal guide to how these templates get used with examples, please see the page ✳=[:a {:href "/reference/template-structure.html"} "A Reference to Fabricate's Page Templates"]🔚.
✳=[:h2 "Constants"]🔚
Expand Down
114 changes: 65 additions & 49 deletions pages/reference/template-structure.html.fab
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
[site.fabricate.prototype.read :as read]
[site.fabricate.prototype.read.grammar :as grammar]
[garden.core :as garden]
[zprint.core :as zp]
[garden.stylesheet :as stylesheet]
[site.fabricate.dev.styles :as styles]
[site.fabricate.prototype.page :as page])) 🔚
Expand All @@ -14,6 +15,11 @@
(concat styles/docs
(list [:.example-rows {:grid-column-start 1}])))})🔚
✳=[:h1 {:class "xl-text"} (:title metadata)]🔚

✳ (defn expr->hiccup [e]
(adorn/clj->hiccup (zp/zprint-str e {:style [:community :justified] :map {:comma? false}}
))) 🔚


This page has an informal explanation of the parts that make up a Fabricate page, using inputs and outputs paired together for demonstration purposes.

Expand All @@ -35,9 +41,12 @@ Useful for: namespace declarations, variable definitions, and other side effects
(:require [site.fabricate.prototype.page :as page]))
(def metadata {:title "My page"})])🔚
✳=(list [:h5 {:class "l-text"} "Examples"]
(apply conj [:div {:class "small"}]
(for [expr run-exprs]
[:pre [:code (page/simple-expr expr {:ctrl-char ""})]])))🔚
(apply conj [:div {:class "small"}]
(for [expr run-exprs]
[:pre (first grammar/delimiters)
[:code {:class "language-clojure"}
(expr->hiccup expr)]
(peek grammar/delimiters)])))🔚

✳=[:h4 (first grammar/delimiters) "= - " "Yield expressions"]🔚
✳(def yield-exprs
Expand All @@ -53,16 +62,16 @@ If you add the "=" character after the asterisk - ✳=[:span (first grammar/deli
Useful for: anything you'd use HTML for.

✳= (list [:h5 {:class "l-text"} "Examples"]
[:div
(apply list
(for [expr yield-exprs]
[:div {:class "example-rows"}
[:div {:class "example-row"}
[:pre (first grammar/delimiters) "="
[:code (adorn/clj->hiccup expr)] (last grammar/delimiters)]]
[:div {:class "example-row"} expr]]))]
[:div
(apply list
(for [expr yield-exprs]
[:div {:class "example-rows"}
[:div {:class "example-row"}
[:pre (first grammar/delimiters) "="
[:code (expr->hiccup expr)] (last grammar/delimiters)]]
[:div {:class "example-row"} expr]]))]

)🔚
)🔚

✳=[:h4 (first grammar/delimiters) "+" "Insert expressions"]🔚
Use this for when you want to evaluate some code and insert the expression into the result, but not its output.
Expand All @@ -87,18 +96,18 @@ Useful for: when you want to demonstrate some code that contributes to the page
(def clifford-example (clifford 1.24 1.14 1.23 1.89))])🔚

✳=(list [:h5 "Examples"]
(apply conj [:div {:class "small"}]
(for [expr insert-exprs]
[:div {:class "example-rows"}

[:pre
{:class "example-row"}
[:code (first grammar/delimiters) "+" (adorn/clj->hiccup expr)
(last grammar/delimiters)]]
[:pre
{:class "example-row"}
[:code (adorn/clj->hiccup expr)]]
])))🔚
(apply conj [:div {:class "small"}]
(for [expr insert-exprs]
[:div {:class "example-rows"}

[:pre
{:class "example-row"}
[:code (first grammar/delimiters) "+" (expr->hiccup expr)
(last grammar/delimiters)]]
[:pre
{:class "example-row"}
[:code (expr->hiccup expr) ]]
])))🔚

✳=[:h4 (first grammar/delimiters) "+=" "Composing control characters"]🔚

Expand Down Expand Up @@ -137,18 +146,19 @@ Useful for: showing off your art alongside the code that produced it.


✳=(list [:h5 "Examples"]
(apply conj [:div]
(for [expr insert-display-exprs]
[:div {:class "example-rows"}

[:pre
{:class "example-row"}
[:code (first grammar/delimiters) "+="
(adorn/clj->hiccup expr) (last grammar/delimiters)]]
[:div
{:class "example-row"}
(eval expr)]
])))🔚
(apply conj [:div]
(for [expr insert-display-exprs]
[:div {:class "example-rows"}

[:pre
{:class "example-row"}
[:code (first grammar/delimiters) "+="
(expr->hiccup expr)
(last grammar/delimiters)]]
[:div
{:class "example-row"}
(eval expr)]
])))🔚

✳=[:h4 "Interlude: (code) documentation as data"]🔚

Expand Down Expand Up @@ -179,23 +189,29 @@ Sometimes it's preferable to group multiple forms together along with paragraphs

This page itself uses many of the "useful for" tips I mentioned in the first section. You might find the source code of the page instructive, so it is included below:

✳=[:pre {:class "small"}
✳=[:pre {:class "small fabricate-src"}

[:code (->>
"pages/reference/template-structure.html.fab"
slurp
(#(read/parse %
{:filename "pages/reference/template-structure.html.fab"}))
(clojure.walk/postwalk
(fn [i] (if (read/fabricate-expr? i)
(let [[start end] grammar/delimiters
ctrl-char
(cond (and (contains? i :expr) (:display i)) "+="
(:display i) "+"
(contains? i :expr) "="
(contains? i :exec) "")]
[:span start ctrl-char
(adorn/clj->hiccup (or (:expr i) (:exec i)))
end])
i)))
(map
(fn [i] (cond (read/fabricate-expr? i)
(let [[start end] grammar/delimiters
ctrl-char
(cond (and (contains? i :expr) (:display i)) "+="
(:display i) "+"
(contains? i :expr) "="
(contains? i :exec) "")]
[:span start ctrl-char
(expr->hiccup

(or (:expr i) (:exec i))

)
end])
(string? i) [:span {:class "fabricate-txt"} i]
:default i
)))
(apply list)) ]]🔚

0 comments on commit cf07024

Please sign in to comment.