From c60d7310663adc4370d086696e303afc91823ca3 Mon Sep 17 00:00:00 2001 From: Frederick Giasson Date: Thu, 18 Dec 2014 09:35:33 -0500 Subject: [PATCH 1/3] Add a new option to exclude source files from being processed by Marginalia. The new option is available at the command line with "-e" or "--exclude". It can also be part of the project.clj file via the ":exclude" keyword. I was requiring this feature because I often have local testing files which I don't want to be included in the documentation. The new option is quite simple: it simply filter out the files that have been identified by the option out of the "sources" var before it is being used by multidoc! or uberdoc! --- README.md | 4 +++- src/marginalia/core.clj | 23 ++++++++++++++++++++--- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fc7fc84..7d50267 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ Marginalia accepts options as described below: * -c --css Additional css resources `;;...` (if not given will be taken from `project.clj`) * -j --js Additional javascript resources `;;...` (if not given will be taken from `project.clj`) * -m --multi Generate each namespace documentation as a separate file + * -e --exclude Exclude source file(s) from the document generation process `;;...` (if not given will be taken from `project.clj`) ### Maven @@ -118,7 +119,8 @@ Marginalia is... - [Tero Parviainen](https://github.com/teropa) - [MerelyAPseudonym](https://github.com/MerelyAPseudonym) - [Ivan](https://github.com/ivantm) -- [benjamin bader] (https://github.com/benjamin-bader) +- [benjamin bader](https://github.com/benjamin-bader) +- [Frederick Giasson](https://github.com/fgiasson) If I've missed your name then please ping me. diff --git a/src/marginalia/core.clj b/src/marginalia/core.clj index 09ffdc2..871b135 100644 --- a/src/marginalia/core.clj +++ b/src/marginalia/core.clj @@ -238,6 +238,17 @@ [(if (= group artifact) artifact (str group "/" artifact)) version]))) +(defn source-excluded? + "Check if a source file is excluded from the generated documentation" + [source opts] + (if-not (empty? + (filter #(if (re-find (re-pattern %) source) + true + false) + (-> opts :marginalia :exclude))) + true + false)) + (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: @@ -249,7 +260,7 @@ If no source files are found, complain with a usage message." [args & [project]] - (let [[{:keys [dir file name version desc deps css js multi leiningen]} files help] + (let [[{:keys [dir file name version desc deps css js multi leiningen exclude]} files help] (cli args ["-d" "--dir" "Directory into which the documentation will be written" :default "./docs"] ["-f" "--file" "File into which the documentation will be written" :default "uberdoc.html"] @@ -263,7 +274,9 @@ ["-j" "--js" "Additional javascript resources ;;... If not given will be taken from project.clj"] ["-m" "--multi" "Generate each namespace documentation as a separate file" :flag true] - ["-l" "--leiningen" "Generate the documentation for a Leiningen project file."]) + ["-l" "--leiningen" "Generate the documentation for a Leiningen project file."] + ["-e" "--exclude" "Exclude source file(s) from the document generation process ;;... + If not given will be taken from project.clj"]) sources (distinct (format-sources (seq files))) sources (if leiningen (cons leiningen sources) sources)] (if-not sources @@ -278,6 +291,7 @@ marg-opts (merge-with choose {:css (when css (.split css ";")) :javascript (when js (.split js ";")) + :exclude (when exclude (.split exclude ";")) :leiningen leiningen} (:marginalia project-clj)) opts (merge-with choose @@ -287,7 +301,10 @@ :dependencies (split-deps deps) :multi multi :marginalia marg-opts} - project-clj)] + project-clj) + sources (->> sources + (filter #(not (source-excluded? % opts))) + (into []))] (println "Generating Marginalia documentation for the following source files:") (doseq [s sources] (println " " s)) From fbb81f04d65e52ad01158d2a1d494e49cfc73f0a Mon Sep 17 00:00:00 2001 From: Frederick Giasson Date: Thu, 18 Dec 2014 13:33:48 -0500 Subject: [PATCH 2/3] Update documentation such that we make clear that the MathJax CDN can be the value of the :javascript key. That way, users don't have to download, install, deploy and carry arround MathJax. --- src/marginalia/html.clj | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/marginalia/html.clj b/src/marginalia/html.clj index 746bbd0..4275c5e 100644 --- a/src/marginalia/html.clj +++ b/src/marginalia/html.clj @@ -131,6 +131,15 @@ ;; to project.clj. Below is a simple example of both inline and block ;; formatted equations. ;; +;; Optionally, you can put the MathJax CDN URL directly as a value of `:javascript` +;; like this: +;; +;; :marginalia { +;; :javascript +;; ["http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"]} +;; +;; That way you won't have to download and carry around the MathJax library. +;; ;; 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}.$$ From a97efcc5f58657c7e42d88b70ca01e60a9acf5ec Mon Sep 17 00:00:00 2001 From: Frederick Giasson Date: Fri, 16 Jan 2015 14:26:16 -0500 Subject: [PATCH 3/3] Fixed documentation to make it consistent --- src/marginalia/core.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/marginalia/core.clj b/src/marginalia/core.clj index 871b135..6274c1b 100644 --- a/src/marginalia/core.clj +++ b/src/marginalia/core.clj @@ -275,7 +275,7 @@ If not given will be taken from project.clj"] ["-m" "--multi" "Generate each namespace documentation as a separate file" :flag true] ["-l" "--leiningen" "Generate the documentation for a Leiningen project file."] - ["-e" "--exclude" "Exclude source file(s) from the document generation process ;;... + ["-e" "--exclude" "Exclude source file(s) from the document generation process ;;... If not given will be taken from project.clj"]) sources (distinct (format-sources (seq files))) sources (if leiningen (cons leiningen sources) sources)]