Skip to content

Commit

Permalink
Add support for {:language :both} option
Browse files Browse the repository at this point in the history 
Author: @ptaoussanis

- This implementation attempts to be minimally invasive.
  Most of the logical changes are within `html/write-index` and
  `html/write-namespaces`, where a special path is introduced
  for "cross-platform" projects (= language `:both`).

- NO behavioural changes are intended for traditional
  (non-cross-platform) projects.

- See weavejester#216 for detailed feature discussion.
  • Loading branch information
@ptaoussanis
ptaoussanis committed Jul 5, 2023
1 parent 492837f commit 732ddaa
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 34 deletions.
25 changes: 24 additions & 1 deletion codox/resources/codox/theme/default/css/default.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ h5.license {
right: 0;
height: 22px;
color: #f5f5f5;
padding: 5px 7px;
padding: 7px 10px;
}

#content {
Expand Down Expand Up @@ -97,6 +97,8 @@ h5.license {
}

#header h1 {
display: block;
float: left;
margin: 0;
padding: 0;
font-size: 18px;
Expand All @@ -121,6 +123,27 @@ h5.license {
color: #f5f5f5;
}

#langs {
display: block;
float: left;
font-size: 16px;
margin: 0 10px;
font-weight: lighter;
}

#langs .lang {
display: inline-block;
margin: 0 2px;
padding: 0 7px;
background-color: #bbb;
border-radius: 6px;
vertical-align: middle;
}

#langs .lang.current {
background-color: #a33;
}

.sidebar a {
color: #333;
}
Expand Down
25 changes: 18 additions & 7 deletions codox/src/codox/main.clj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,14 +58,24 @@
(filter #(some (partial ns-matches? %) ns-filters) namespaces)
namespaces))

(defn- cross-platform?
"Do given options indicate *both* Clojure and ClojureScript sources?"
[{:keys [language] :as opts}]
(= language :both))

(defn- read-namespaces
"Returns {<language> <namespace-seq>} for cross-platform opts,
or <namespace-seq> otherwise."
[{:keys [language root-path source-paths namespaces metadata exclude-vars] :as opts}]
(let [reader (namespace-readers language)]
(-> (reader source-paths (select-keys opts [:exception-handler]))
(filter-namespaces namespaces)
(remove-excluded-vars exclude-vars)
(add-source-paths root-path source-paths)
(add-ns-defaults metadata))))
(if (cross-platform? opts)
{:clojure (read-namespaces (assoc opts :language :clojure))
:clojurescript (read-namespaces (assoc opts :language :clojurescript))}
(let [reader (namespace-readers language)]
(-> (reader source-paths (select-keys opts [:exception-handler]))
(filter-namespaces namespaces)
(remove-excluded-vars exclude-vars)
(add-source-paths root-path source-paths)
(add-ns-defaults metadata)))))

(defn- read-documents [{:keys [doc-paths doc-files] :or {doc-files :all}}]
(cond
Expand Down Expand Up @@ -105,4 +115,5 @@
documents (read-documents options)]
(write-fn (assoc options
:namespaces namespaces
:documents documents)))))
:documents documents
:cross-platform? (cross-platform? options))))))
137 changes: 111 additions & 26 deletions codox/src/codox/writer/html.clj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,18 @@
(if-let [doc (:doc metadata)]
(markdown-to-html doc project ns))])

(defn- language-fileext
[language]
(case language
:clojure ".clj"
:clojurescript ".cljs"
nil ""))

(defn- index-filename [language]
(str "index" (language-fileext language) ".html"))

(defn- ns-filename [namespace]
(str (:name namespace) ".html"))
(str (:name namespace) (language-fileext (:language namespace)) ".html"))

(defn- ns-filepath [output-dir namespace]
(str output-dir "/" (ns-filename namespace)))
Expand Down Expand Up @@ -235,11 +245,12 @@
[:span.bottom]])))

(defn- index-link [project on-index?]
(list
[:h3.no-link [:span.inner "Project"]]
[:ul.index-link
[:li.depth-1 {:class (if on-index? "current")}
(link-to "index.html" [:div.inner "Index"])]]))
(when-not (:cross-platform? project)
(list
[:h3.no-link [:span.inner "Project"]]
[:ul.index-link
[:li.depth-1 {:class (if on-index? "current")}
(link-to "index.html" [:div.inner "Index"])]])))

(defn- topics-menu [project current-doc]
(if-let [docs (seq (:documents project))]
Expand Down Expand Up @@ -275,16 +286,26 @@
(get-in project [:html :namespace-list] default)))

(defn- namespaces-menu [project current-ns]
(let [namespaces (:namespaces project)]
(when (:show-namespaces? project)
(let [namespaces (:namespaces project)]
(list
[:h3.no-link [:span.inner "Namespaces"]]
(case (namespace-list-type project)
:flat (flat-namespaces namespaces current-ns)
:nested (nested-namespaces namespaces current-ns))))))

(defn- platforms-menu [project]
(when (:show-platforms? project)
(list
[:h3.no-link [:span.inner "Namespaces"]]
(case (namespace-list-type project)
:flat (flat-namespaces namespaces current-ns)
:nested (nested-namespaces namespaces current-ns)))))
[:h3.no-link [:span.inner "Platforms"]]
[:ul.index-link
[:li.depth-1 (link-to (index-filename :clojure) [:div.inner "Clojure"])]
[:li.depth-1 (link-to (index-filename :clojure) [:div.inner "ClojureScript"])]])))

(defn- primary-sidebar [project & [current]]
[:div.sidebar.primary
(index-link project (nil? current))
(platforms-menu project)
(topics-menu project current)
(namespaces-menu project current)])

Expand Down Expand Up @@ -314,10 +335,23 @@
[:span.project-name (h (:name project))] " "
[:span.project-version (h (:version project))]])

(defn- header-platforms [project]
(when (:cross-platform? project)
(let [{:keys [language]} project]
[:div#langs
(if (= language :clojure)
[:div.lang.current "clj"]
[:div.lang (link-to (index-filename :clojure) "clj")])

(if (= language :clojurescript)
[:div.lang.current "cljs"]
[:div.lang (link-to (index-filename :clojurescript) "cljs")])])))

(defn- header [project]
[:div#header
[:h2 "Generated by " (link-to "https://github.com/weavejester/codox" "Codox")]
[:h1 (link-to "index.html" (project-title project))]])
[:h1 (link-to "index.html" (project-title project))]
(header-platforms project)])

(defn- package [project]
(if-let [p (:package project)]
Expand Down Expand Up @@ -360,16 +394,28 @@
[:ul.topics
(for [doc docs]
[:li (link-to (doc-filename doc) (h (:title doc)))])]))
[:h2 "Namespaces"]
(for [namespace (sort-by :name (:namespaces project))]
[:div.namespace
[:h3 (link-to (ns-filename namespace) (h (:name namespace)))]
[:div.doc (format-docstring project nil (update-in namespace [:doc] util/summary))]
[:div.index
[:p "Public variables and functions:"]
(unordered-list
(for [var (sorted-public-vars namespace)]
(list " " (link-to (var-uri namespace var) (h (:name var))) " ")))]])]]))

(when (:show-platforms? project)
(list
[:h2 "Platforms"]
[:p "This project includes both Clojure and ClojureScript code, please "
[:strong "choose a platform"] " to view its documentation:"]
[:ul
[:li (link-to (index-filename :clojure) "Clojure")]
[:li (link-to (index-filename :clojurescript) "ClojureScript")]]))

(when (:show-namespaces? project)
(list
[:h2 "Namespaces"]
(for [namespace (sort-by :name (:namespaces project))]
[:div.namespace
[:h3 (link-to (ns-filename namespace) (h (:name namespace)))]
[:div.doc (format-docstring project nil (update-in namespace [:doc] util/summary))]
[:div.index
[:p "Public variables and functions:"]
(unordered-list
(for [var (sorted-public-vars namespace)]
(list " " (link-to (var-uri namespace var) (h (:name var))) " ")))]])))]]))

(defmulti format-document
"Format a document into HTML."
Expand Down Expand Up @@ -465,12 +511,51 @@
(.mkdirs (io/file output-dir dir))))

(defn- write-index [output-dir project]
(spit (io/file output-dir "index.html") (transform-html project (index-page project))))
(let [{:keys [namespaces cross-platform?]} project]

(when cross-platform?
;; Write an index file for each language
(doseq [language (keys namespaces)]
(let [namespaces (map #(assoc % :language language) (get namespaces language))
project
(assoc project
:namespaces namespaces
:language language
:show-platforms? false
:show-namespaces? true)]
(spit (io/file output-dir (index-filename language))
(transform-html project (index-page project))))))

;; Always write a main index file
(let [project (assoc project
:show-platforms? cross-platform?
:show-namespaces? (not cross-platform?))]
(spit (io/file output-dir (index-filename nil))
(transform-html project (index-page project))))))

(defn- write-namespaces [output-dir project]
(doseq [namespace (:namespaces project)]
(spit (ns-filepath output-dir namespace)
(transform-html project (namespace-page project namespace)))))
(let [{:keys [namespaces cross-platform?]} project]

(if cross-platform?
;; Write namespace files for each language
(doseq [language (keys namespaces)]
(let [namespaces (map #(assoc % :language language) (get namespaces language))]
(doseq [namespace namespaces]
(let [project (assoc project
:namespaces namespaces
:language language
:show-platforms? false
:show-namespaces? true)]
(spit (ns-filepath output-dir namespace)
(transform-html project (namespace-page project namespace)))))))

;; Write namespace files for only language
(doseq [namespace namespaces]
(let [project (assoc project
:show-platforms? false
:show-namespaces? true)]
(spit (ns-filepath output-dir namespace)
(transform-html project (namespace-page project namespace))))))))

(defn- write-documents [output-dir project]
(doseq [document (:documents project)]
Expand Down

0 comments on commit 732ddaa

Please sign in to comment.