diff --git a/example-output/uberdoc.html b/example-output/uberdoc.html index 003b0be..eac8d53 100644 --- a/example-output/uberdoc.html +++ b/example-output/uberdoc.html @@ -2525,37 +2525,8 @@ $(document).ready(function() { font-style: italic !important; color: #2a00ff !important; } -Marginalia Output

marginalia

0.2.1


lightweight literate programming for clojure -- inspired by docco

-

dependencies

org.clojure/clojure
1.2.0
org.clojars.nakkaya/markdownj
1.0.2b4
hiccup
0.3.0

dev dependencies

lein-clojars
0.5.0-SNAPSHOT
jline
0.9.94
swank-clojure
1.2.1
hiccup
0.3.0
org.clojars.nakkaya/markdownj
1.0.2b4
marginalia
0.2.1

cake plugin namespaces

  • marginalia.tasks



(this space intentionally left blank)

namespaces

 

leiningen.marg

toc

Leiningen plugin for running marginalia against your project.

- -

Usage

- -
    -
  1. Add [marginalia "0.2.0"] to your project.clj's :dev-dependencies section.
    2. -
  2. run lein marg from your project's root directory.
    3. -
-
(ns leiningen.marg
-  (:use [marginalia.core]))
-
-(defn marg [project & args]
-  (run-marginalia args))

You can pass a file, directory, multiple files and/or directories to marginalia like so:

- -
$ lein marg  # runs marginalia on all the cljs found in your ./src dir.
-$ lein marg ./path/to/files  # runs marginalia on all cljs found in ./path/to/files
-$ lein marg ./path/to/file.clj  # runs marginalia on ./path/to/file.clj only.
-$ lein marg ./path/to/one.clj ./path/to/another.clj
-$ lein marg ./path/to/dir ./path/to/some/random.clj
-
- -

This allows you to control the order in which sections appear in the generated -documentation. For example, in marginalia's docs, the leiningen.marg namespace -forced to the bottom of the namespace ordering by using this command:

- -
$ lein marg ./src/marginalia ./src/leiningen
-
-
-
-
 

marginalia.core

toc

Core provides all of the functionality around parsing clojure source files +Marginalia Output

marginalia

0.2.1


lightweight literate programming for clojure -- inspired by docco

+

dependencies

org.clojure/clojure
1.2.0
org.clojars.nakkaya/markdownj
1.0.2b4
hiccup
0.3.0

dev dependencies

lein-clojars
0.5.0-SNAPSHOT
jline
0.9.94
swank-clojure
1.2.1
hiccup
0.3.0
org.clojars.nakkaya/markdownj
1.0.2b4
marginalia
0.2.1

cake plugin namespaces

  • marginalia.tasks



(this space intentionally left blank)

namespaces

 

marginalia.core

toc

Core provides all of the functionality around parsing clojure source files into an easily consumable format.

(ns marginalia.core
   (:require [clojure.java.io :as io]
@@ -2569,7 +2540,9 @@ into an easily consumable format.

 
(def *comment* #"^\s*;;\s?")
(def *divider-text* "\n;;DIVIDER\n")
 (def *divider-html* #"\n*<span class=\"c[1]?\">;;DIVIDER</span>\n*")

File System Utilities

-

+
Performs roughly the same task as the UNIX ls.  That is, returns a seq of the filenames
+at a given directory.  If a path to a file is supplied, then the seq contains only the
+original path given.

 
 (defn ls
   [path]
@@ -2580,36 +2553,38 @@ into an easily consumable format.

         [path]))))

 
 (defn mkdir [path]
-  (.mkdirs (io/file path)))

+  (.mkdirs (io/file path)))
Ensure that the directory specified by path exists.  If not then make it so.
+Here is a snowman ☃

 
-(defn ensure-directory! [path]
+(defn ensure-directory!
+  [path]
   (when-not (ls path)
     (mkdir path)))

 
 (defn dir? [path]
   (.isDirectory (java.io.File. path)))
Returns a seq of clojure file paths (strings) in alphabetical depth-first order (I think?).

 
-(defn find-clojure-file-paths [dir]
+(defn find-clojure-file-paths
+  [dir]
   (->> (java.io.File. dir)
        (file-seq)
        (filter #(re-find #"\.clj$" (.getAbsolutePath %)))
-       (map #(.getAbsolutePath %))))
-
Project Info Parsing

+       (map #(.getAbsolutePath %))))
Project Info Parsing

 
 
Marginalia will parse info out of your project.clj to display in
 the generated html file's header.

 
-
TODO: add pom.xml support.

+
TODO add pom.xml support.

 
 
 
 
Parses a project.clj file and returns a map in the following form

 
-
ex. {:name 
-     :version
-     :dependencies
-     :dev-dependencies
-     etc...}
+
{:name 
+ :version
+ :dependencies
+ :dev-dependencies
+ etc...}
 

 
 
by reading the defproject form from your project.clj to obtain name and
@@ -2671,28 +2646,28 @@ version, then merges in the rest of the defproject forms (:dependencies
(defn docstring-line? [line sections]
   (let [l (last sections)
         last-code-text (get l :code-text "")]
-    (try
Is the last line's code-text a defn, and does the
-current line start with a quote?

+    (try
Last line contain defn &&
+last line not contain what looks like a param vector &&
+current line start with a quote 

 
      (or
-       (and (re-find #"\(defn" last-code-text)
Is the last line's code-text a deftask, and does the
+       (and (re-find #"\(defn" last-code-text)
+            (not (re-find #"\[.*\]" last-code-text))
Is the last line's code-text a deftask, and does the
 current line start with a quote?

 
            (re-find #"^\"" (str/trim (str line))))
-       (and (re-find #"\(deftask" last-code-text)
Is the last line's code-text the start of a ns
+       (and (re-find #"^\(deftask" (str/trim last-code-text))
Is the last line's code-text the start of a ns
 decl, and does the current line start with a quote?

 
            (re-find #"^\"" (str/trim (str line))))
-       (and (re-find #"\(ns" last-code-text)
Is the prev line a docstring line, the current line not
-start with a ( or [ or {, and the current line not an empty string?

+       (and (re-find #"^\(ns" last-code-text)
Is the prev line a docstring, prev line not end with a quote,
+and the current line empty?

 
            (re-find #"^\"" (str/trim (str line))))
-       (and (:docstring-text l)
-            (not (re-find #"^\(" (str/trim (str line))))
-            (not (re-find #"^\[" (str/trim (str line))))
-            (not (re-find #"^\{" (str/trim (str line))))
Is the prev line a docstring, the prev line not end with a quote,
+       (and (:docstring-text l)
Is the prev line a docstring, the prev line not end with a quote,
 and the current line not an empty string?

-
            (not= "" (str/trim (str line))))
+
            (not (re-find #"\"$" (str/trim (:docstring-text l)))))
        (and (:docstring-text l)
-            (not (re-find #"\"$" (str/trim (:docstring-text l))))
+            (not (re-find #"[^\\]\"$" (str/trim (:docstring-text l))))
             (= "" (str/trim (str line)))))
-      (catch Exception e nil))))

+      (catch Exception e nil))))
+

 
 (defn parse [src]
   (loop [[line & more] (line-seq src) cnum 1 dnum 0 sections []]
@@ -2743,7 +2718,8 @@ I wonder?

 
  • The path to spit the result (output-file-name)
    • 
 
 
    -(defn uberdoc! [output-file-name files-to-analyze]
+(defn uberdoc!
+  [output-file-name files-to-analyze]
   (let [docs (map path-to-doc files-to-analyze)
         source (uberdoc-html
                 output-file-name
@@ -2784,7 +2760,8 @@ Multi line
    
 
     (defn -main
   [sources]
-  (run-marginalia sources))
    Example Usage
    
+  (run-marginalia sources))
+
    Example Usage
    
 
     (comment
    Command line example
    
 
    @@ -2826,7 +2803,8 @@ Multi line
    
 
    ex. (css [:h1 {:color "blue"}] [:div.content p {:text-indent "1em"}])
 → h1 {color: blue;} div.content p {text-indent: 1em;}
    
 
    -(defn css [& rules]
+(defn css
+  [& rules]
   (html [:style {:type "text/css"}
          (apply str (map css-rule rules))]))
    Stolen from leiningen
    
 
    @@ -2852,10 +2830,11 @@ Multi line
    
 based) for display through html & css.
    
 
    
 
    Markdown processor.
    
-
    (def mdp (com.petebevin.markdown.MarkdownProcessor.))
    Markdown string to html converter. Translates strings like "# header!
-→ "<h1>header!</h1>
    
+
    (def mdp (com.petebevin.markdown.MarkdownProcessor.))
    Markdown string to html converter. Translates strings like "# header!
    
 
    -(defn md [s]
+(defn md 
+   -> \"<h1>header!</h1>"
+  [s]
   (.markdown mdp s))
    Inserts super-fancy characters into the doc section.
    
 
     (defn replace-special-chars
@@ -2932,7 +2911,33 @@ outlined above.
    
     (html [:div {:class "plugins"}
            [:h3 "cake plugin namespaces"]
            [:ul
-            (map #(vector :li %) tasks)]])))
    Is 
     overloaded?  Maybe we should consider redistributing
    
+            (map #(vector :li %) tasks)]])))
    Load Optional Resources
    
+
+
    Use external Javascript and CSS in your documentation. For example:
+To format Latex math equations, download the
+MathJax Javascript library to the docs
+directory and then add
    
+
+
    :marginalia {:javascript ["mathjax/MathJax.js"]}
+
    
+
+
    to project.clj. Below is a simple example of both inline and block
+formatted equations.
    
+
+
    When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
+$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
    
+
    Generate script and link tags for optional external javascript and css.
    
+
    +(defn opt-resources-html
+  [project-info]
+  (let [options (:marginalia project-info) 
+        javascript (:javascript options)
+        css (:css options)]
+    (html (concat
+           (when javascript
+             (map #(vector :script {:type "text/javascript" :src %}) javascript))
+           (when css
+             (map #(vector :link {:tyle "text/css" :rel "stylesheet" :href %}) css))))))
    Is 
     overloaded?  Maybe we should consider redistributing
    
 
    header numbers instead of adding classes to all the h1 tags.
    
 
    (defn header-html [project-info]
   (html
@@ -3111,7 +3116,8 @@ outlined above.
    
 & inline-css) to be able to package the output as a single file (uberdoc if you will).  It goes without
 saying that all this is WIP and will prabably change in the future.
    
 
    -(defn page-template [header toc floating-toc content]
+(defn page-template
+  [opt-resources header toc floating-toc content]
   (html
    (doctype :html5)
    [:html
@@ -3130,6 +3136,7 @@ saying that all this is WIP and will prabably change in the future.
    
      header-css
      floating-toc-css
      general-css
+     opt-resources
      [:title "Marginalia Output"]]
     [:body
      [:table
@@ -3156,6 +3163,7 @@ It's probably the only var consumers will use.
    
 (defn uberdoc-html
   [output-file-name project-metadata docs]
   (page-template
+   (opt-resources-html project-metadata)
    (header-html project-metadata)
    (toc-html docs)
    (floating-toc-html docs)
@@ -3165,7 +3173,7 @@ It's probably the only var consumers will use.
    
 
    Usage
    
 
 
      
-
    1. In your project.clj, add [marginalia "0.2.0"] to your:dev-dependenciesandmarginalia.tasksto:tasks`
      2. 
+
    2. In your project.clj, add [marginalia "0.2.1"] to your:dev-dependenciesandmarginalia.tasksto:tasks`
      3. 
 
    3. Run cake marg from within your project directory.
      4. 
 
    
 
    (ns marginalia.tasks
@@ -3175,5 +3183,44 @@ Optionally, you can pass files or directories to control what documentation is g
 
     (deftask marg
   {files :marg}
-  (run-marginalia files))
     
    Generated by marginalia.  Syntax highlighting provided by Alex Gorbatchev's SyntaxHighlighter
    • leiningen.marg
    • marginalia.core
    • marginalia.html
    • marginalia.tasks
    
\ No newline at end of file
diff --git a/src/marginalia/core.clj b/src/marginalia/core.clj
index f6059ea..9a6bffd 100644
--- a/src/marginalia/core.clj
+++ b/src/marginalia/core.clj
@@ -39,8 +39,9 @@
 (defn dir? [path]
   (.isDirectory (java.io.File. path)))
 
-(defn find-clojure-file-paths [dir]
+(defn find-clojure-file-paths
   "Returns a seq of clojure file paths (strings) in alphabetical depth-first order (I think?)."
+  [dir]
   (->> (java.io.File. dir)
        (file-seq)
        (filter #(re-find #"\.clj$" (.getAbsolutePath %)))
@@ -201,12 +202,13 @@
 
 ;; ## Ouput Generation
 
-(defn uberdoc! [output-file-name files-to-analyze]
+(defn uberdoc!
   "Generates an uberdoc html file from 3 pieces of information:
 
    1. Results from processing source files (`path-to-doc`)
    2. Project metadata obtained from `parse-project-file`.
    3. The path to spit the result (`output-file-name`)"
+  [output-file-name files-to-analyze]
   (let [docs (map path-to-doc files-to-analyze)
         source (uberdoc-html
                 output-file-name
diff --git a/src/marginalia/html.clj b/src/marginalia/html.clj
index 3fc7e75..82b6918 100644
--- a/src/marginalia/html.clj
+++ b/src/marginalia/html.clj
@@ -22,11 +22,12 @@
     (str (apply str (interpose " " (map name sels)))
          "{" (apply str (map #(str (name (key %)) ":" (val %) ";") props)) "}")))
 
-(defn css [& rules]
+(defn css
   "Quick and dirty dsl for inline css rules, similar to hiccup.
 
    ex. `(css [:h1 {:color \"blue\"}] [:div.content p {:text-indent \"1em\"}])`
    -> `h1 {color: blue;} div.content p {text-indent: 1em;}`"
+  [& rules]
   (html [:style {:type "text/css"}
          (apply str (map css-rule rules))]))
 
@@ -57,9 +58,10 @@
 ;; Markdown processor.
 (def mdp (com.petebevin.markdown.MarkdownProcessor.))
 
-(defn md [s]
+(defn md 
   "Markdown string to html converter. Translates strings like \"# header!\"
    -> \"
    header!
    "
+  [s]
   (.markdown mdp s))
 
 (defn replace-special-chars
@@ -345,10 +347,11 @@
    [:.syntaxhighlighter :code {:font-size "13px"}]
    [:.footer {:text-align "center"}]))
 
-(defn page-template [opt-resources header toc floating-toc content]
+(defn page-template
   "Notice that we're inlining the css & javascript for [SyntaxHighlighter](http://alexgorbatchev.com/SyntaxHighlighter/) (`inline-js`
    & `inline-css`) to be able to package the output as a single file (uberdoc if you will).  It goes without
    saying that all this is WIP and will prabably change in the future."
+  [opt-resources header toc floating-toc content]
   (html
    (doctype :html5)
    [:html