Adds more comments, rejiggers a few fns.
- Breaks project content parsing into separate fn to use destructuring instead of second, nth, and drop.
This commit is contained in:
parent
d0c07ff9f0
commit
e602711bec
1 changed files with 45 additions and 25 deletions
|
@ -37,11 +37,13 @@
|
||||||
(when-not (ls path)
|
(when-not (ls path)
|
||||||
(mkdir path)))
|
(mkdir path)))
|
||||||
|
|
||||||
(defn dir? [path]
|
(defn dir?
|
||||||
|
"Many Marginalia fns use dir? to recursively search a filepath."
|
||||||
|
[path]
|
||||||
(.isDirectory (java.io.File. path)))
|
(.isDirectory (java.io.File. path)))
|
||||||
|
|
||||||
(defn find-clojure-file-paths
|
(defn find-clojure-file-paths
|
||||||
"Returns a seq of clojure file paths (strings) in alphabetical depth-first order (I think?)."
|
"Returns a seq of clojure file paths (strings) in alphabetical depth-first order."
|
||||||
[dir]
|
[dir]
|
||||||
(->> (java.io.File. dir)
|
(->> (java.io.File. dir)
|
||||||
(file-seq)
|
(file-seq)
|
||||||
|
@ -55,30 +57,32 @@
|
||||||
;; ![TODO](http://images.fogus.me/badges/todo.png "POM") add pom.xml support.
|
;; ![TODO](http://images.fogus.me/badges/todo.png "POM") add pom.xml support.
|
||||||
|
|
||||||
|
|
||||||
|
(defn parse-project-form
|
||||||
|
"Pulls apart the seq of project information and assembles it into a map of
|
||||||
(defn parse-project-file
|
the following form
|
||||||
"Parses a project.clj file and returns a map in the following form
|
|
||||||
|
|
||||||
{:name
|
{:name
|
||||||
:version
|
:version
|
||||||
:dependencies
|
:dependencies
|
||||||
:dev-dependencies
|
:dev-dependencies
|
||||||
etc...}
|
etc...}
|
||||||
|
by merging into the name and version information the rest of the defproject
|
||||||
|
forms (`:dependencies`, etc)"
|
||||||
|
[[_ project-name version-number & attributes]]
|
||||||
|
(merge {:name (str project-name)
|
||||||
|
:version version-number}
|
||||||
|
(apply hash-map attributes)))
|
||||||
|
|
||||||
by reading the `defproject` form from your project.clj to obtain name and
|
(defn parse-project-file
|
||||||
version, then merges in the rest of the defproject forms (`:dependencies`, etc)."
|
"Parses a project file -- './project.clj' by default -- and returns a map
|
||||||
|
assembled according to the logic in parse-project-form."
|
||||||
([] (parse-project-file "./project.clj"))
|
([] (parse-project-file "./project.clj"))
|
||||||
([path]
|
([path]
|
||||||
(try
|
(try
|
||||||
(let [rdr (clojure.lang.LineNumberingPushbackReader.
|
(let [rdr (clojure.lang.LineNumberingPushbackReader.
|
||||||
(java.io.FileReader.
|
(java.io.FileReader.
|
||||||
(java.io.File. path)))
|
(java.io.File. path)))]
|
||||||
project-form (read rdr)]
|
(parse-project-form (read rdr)))
|
||||||
(merge {:name (str (second project-form))
|
(catch Exception e
|
||||||
:version (nth project-form 2)}
|
|
||||||
(apply hash-map (drop 3 project-form))))
|
|
||||||
(catch Exception e
|
|
||||||
(throw (Exception.
|
(throw (Exception.
|
||||||
(str
|
(str
|
||||||
"There was a problem reading the project definition from "
|
"There was a problem reading the project definition from "
|
||||||
|
@ -87,8 +91,8 @@
|
||||||
|
|
||||||
;; ## Source File Analysis
|
;; ## Source File Analysis
|
||||||
|
|
||||||
;; This line should be replaced
|
;; Marginalia will parse your code to extract doc strings for display in the
|
||||||
;; and this one too!
|
;; generated html file.
|
||||||
(defn parse [src]
|
(defn parse [src]
|
||||||
(for [line (line-seq src)]
|
(for [line (line-seq src)]
|
||||||
(if (re-find *comment* line)
|
(if (re-find *comment* line)
|
||||||
|
@ -222,23 +226,29 @@
|
||||||
(defn uberdoc!
|
(defn uberdoc!
|
||||||
"Generates an uberdoc html file from 3 pieces of information:
|
"Generates an uberdoc html file from 3 pieces of information:
|
||||||
|
|
||||||
1. Results from processing source files (`path-to-doc`)
|
|
||||||
2. The path to spit the result (`output-file-name`)
|
2. The path to spit the result (`output-file-name`)
|
||||||
|
1. Results from processing source files (`path-to-doc`)
|
||||||
3. Project metadata as a map, containing at a minimum the following:
|
3. Project metadata as a map, containing at a minimum the following:
|
||||||
- :name
|
- :name
|
||||||
- :version
|
- :version
|
||||||
"
|
"
|
||||||
[output-file-name files-to-analyze props]
|
[output-file-name files-to-analyze props]
|
||||||
(let [docs (map path-to-doc files-to-analyze)
|
(spit output-file-name
|
||||||
source (uberdoc-html
|
(uberdoc-html
|
||||||
output-file-name
|
output-file-name
|
||||||
props
|
(map path-to-doc files-to-analyze)
|
||||||
(map path-to-doc files-to-analyze))]
|
props)))
|
||||||
(spit output-file-name source)))
|
|
||||||
|
|
||||||
;; ## External Interface (command-line, lein, cake, etc)
|
;; ## External Interface (command-line, lein, cake, etc)
|
||||||
|
|
||||||
(defn format-sources [sources]
|
;; These functions support Marginalia's use by client software or command-line
|
||||||
|
;; users.
|
||||||
|
|
||||||
|
(defn format-sources
|
||||||
|
"Given a collection of filepaths, returns a lazy sequence of filepaths to
|
||||||
|
all .clj files on those paths: directory paths will be searched recursively
|
||||||
|
for .clj files."
|
||||||
|
[sources]
|
||||||
(if (nil? sources)
|
(if (nil? sources)
|
||||||
(find-clojure-file-paths "./src")
|
(find-clojure-file-paths "./src")
|
||||||
(->> sources
|
(->> sources
|
||||||
|
@ -250,7 +260,17 @@
|
||||||
(defn usage []
|
(defn usage []
|
||||||
(println "marginalia <src1> ... <src-n>"))
|
(println "marginalia <src1> ... <src-n>"))
|
||||||
|
|
||||||
(defn run-marginalia [sources]
|
(defn run-marginalia
|
||||||
|
"Default generation: given a collection of filepaths in a project, find the .clj
|
||||||
|
files at these paths and, if Clojure source files are found:
|
||||||
|
|
||||||
|
1. Print out a message to std out letting a user know which files are to be processed;
|
||||||
|
1. Create the docs directory inside the project folder if it doesn't already exist;
|
||||||
|
1. Call the uberdoc! function to generate the output file at its default location,
|
||||||
|
using the found source files and a project file expected to be in its default location.
|
||||||
|
|
||||||
|
If no source files are found, complain with a usage message."
|
||||||
|
[sources]
|
||||||
(let [sources (format-sources sources)]
|
(let [sources (format-sources sources)]
|
||||||
(if-not sources
|
(if-not sources
|
||||||
(do
|
(do
|
||||||
|
|
Loading…
Reference in a new issue