docy snippets added

README.md

@@ -6,7 +6,7 @@
 - Docy shows dynamically customizable documentation for clojure namespaces.
 - Generated Documentation can be shown statically (say on github pages)
 - or it can be run interactively, which allows evaluating discovered examples.
-
+- snippets (with fully functional floating repl) can be linked to any function.
 
 
 # demo

demo/deps.edn

@@ -3,7 +3,8 @@
          ]
  :deps
  {org.clojure/clojure    {:mvn/version "1.11.3"}
-  org.pinkgorilla/goldly-docs {:mvn/version "0.8.34"}
+  ;org.pinkgorilla/goldly-docs {:mvn/version "0.8.34"}
+  org.pinkgorilla/goldly-docs {:mvn/version "0.8.37"}
   io.github.pink-gorilla/docy {:local/root ".." :deps/manifest :deps}
   ; libs we want to document
   scicloj/tablecloth {:mvn/version "7.021"} ; brings techml-dataset

demo/resources/ext/demo.edn

@@ -0,0 +1,8 @@
+{:name "demo-docy"
+ :lazy true
+ :cljs-routes {""  reval.page.viewer/viewer-page
+               ; "devtools/repl" :repl
+               "frepl" demo.page.snippets/snippets-page}
+
+;
+ }

demo/src/config.edn

@@ -27,8 +27,21 @@
               {:kb "ctrl-shift-enter" :handler [:notebook/evaluate-all]         :desc "Evaluate all segments"}
               {:kb "ctrl-enter" :handler [:repl/eval-expression]               :desc "Evaluate the highlighted segment"}]
 
-:docy [; external 
-       tablecloth.api
-       ]
-
+:docy {:namespaces [; external 
+                    tablecloth.api]
+       :snippets
+         [{:ns "demo.notebook.movies"
+           :kernel :clj
+           :label "print table (simple)"
+           :fns ["tablecloth.api/aggregate"
+                 "tablecloth.api/columns"]}
+          {:ns "demo.notebook.simple"
+           :kernel :clj
+           :label "range"
+           :fns ["tablecloth.api/aggregate"
+                 "tablecloth.api/columns"
+                 "tablecloth.api/concat"]
+           }]}
+
+;
 }

demo/src/demo/dev.clj

@@ -0,0 +1,18 @@
+(ns demo.dev
+  (:require
+   [clojure.string :as string]
+   [modular.system]
+   [docy.core :refer [docy-data]]))
+
+  ;; first lets get the running reval  instance
+(def s (modular.system/system :docy))
+
+
+
+(def data 
+  (docy-data s)
+  )
+
+data
+
+(get-in data [:snippet-dict "tablecloth.api/concat"])

demo/src/demo/notebook/movies.clj

@@ -0,0 +1,26 @@
+(ns demo.notebook.movies
+  (:require
+   [clojure.pprint :refer [print-table]]))
+
+(println "hello\nworld!")
+
+(defn add3 [v]
+  (+ 3 v))
+
+(def movies
+  [{:name "Terminator" :year 1984 :studio "Hemdale" :producer "Gale Anne Hurd"}
+   {:name "Men in Black" :year 1997 :studio "Amblin Entertainment" :producer "Walter F. Parkes"}
+   {:name "Matrix" :year 1999 :studio "Warner Bros" :producer "Joel Silver"}
+   {:name "Dr. Strange" :year 2016 :studio "Marvel Studios" :producer "Scott Derrickson"}])
+
+*ns*
+
+(print-table movies)
+
+
+(def more-movies
+  (conj movies {:name "Harry Potter" :year 2020}))
+
+(count more-movies)
+
+

demo/src/demo/notebook/simple.clj

@@ -0,0 +1,4 @@
+(ns demo.notebook.simple)
+
+
+(range 20)

demo/src/demo/page/snippets.cljs

@@ -0,0 +1,42 @@
+(ns demo.page.snippets
+  (:require
+   [reval.frepl :refer [show-floating-repl show-floating-repl-namespace]]
+   [docy.snippet :refer [snippet-list]]))
+
+
+(def snippets
+  [{:ns "demo.notebook.movies"
+    :kernel :clj
+    :label "print table (simple)"}
+   {:ns "demo.notebook.simple"
+    :kernel :clj
+    :label "range"}])
+
+
+(defn snippets-page [{:keys [route-params query-params handler] :as route}]
+  [:div
+   [:h1 "I am a normal reagent page. But I can add a floating repl."]
+
+   ;; just code
+   [:a {:on-click #(show-floating-repl {:code "(+ 1 2 3)"})}
+    [:p "show code (floating)"]]
+
+   ;; code with a example result saved.
+   [:a {:on-click #(show-floating-repl {:code "(+ 1 2 3)"
+                                        :render-fn 'reval.viz.render-fn/reagent
+                                        :data ^{:hiccup true}
+                                        [:span {:style {:color "blue"}} "25"]})}
+    [:p "show code (eval result)"]]
+
+   ;; load a namespace
+   [:a {:on-click #(show-floating-repl-namespace {:ns "notebook.study.movies"
+                                                  :kernel :clj})}
+    [:p "show code (namespace)"]]
+
+
+   [:a {:on-click #(show-floating-repl-namespace {:ns "demo.notebook.highcharts"
+                                                  :kernel :clj})}
+    [:p "show code (highcharts)"]]
+
+   [:h1 "now as a list:"]
+   [snippet-list snippets]])

demo/src/services.edn

@@ -38,7 +38,9 @@
                  {:exts (clip/ref :exts)
                   :clj (clip/ref :clj-service)
                   :role nil
-                  :namespaces (:docy (deref (clip/ref :config)))})}
+                  :namespaces (:namespaces (:docy (deref (clip/ref :config))))
+                  :snippets (:snippets (:docy (deref (clip/ref :config))))
+                  })}
 
 
 

src/docy/core.clj

@@ -1,88 +1,36 @@
 (ns docy.core
   (:require
-   [orchard.info :as orchard]
    [taoensso.timbre :refer [info warn error]]
    [extension :as ext]
-   [clj-service.core :refer [expose-functions]]))
-
-(defn docstring [symbol]
-  (:doc (meta (resolve symbol))))
-
-(defn describe-fun [nss fun]
-  (let [data (orchard/info nss fun)]
-    (merge
-     data
-     {:ns (str (:ns data))
-      :name (str (:name data))})))
-
-
-(defn describe-ns [nss]
-  (require [nss])
-  (let [symbols (keys (ns-publics nss))]
-    {:ns (str nss)
-     :names (->> symbols
-                 (map #(describe-fun nss %))
-                 (filter :doc)
-                 (remove :deprecated ) 
-                 (sort-by :name)
-                 )}))
-
-(defn build-namespaces [ns-symbol-seq]
-  (info "building namespaces: " (count ns-symbol-seq))
-  (let [r (->> (map describe-ns ns-symbol-seq)
-               (sort-by :ns)
-               ;(take 1)
-               (into []))]
-    ;(info "result: " r)
-    r))
-
-(defn start-docy [{:keys [exts clj role namespaces]}]
+   [clj-service.core :refer [expose-functions]]
+   [docy.namespace :refer [build-namespaces ns-seq->dict]]
+   [docy.snippet :refer [build-fn-lookup]]))
+
+(defn docy-data [{:keys [namespaces snippets]}]
+  (let [ns-seq (build-namespaces namespaces)
+        ns-dict (ns-seq->dict ns-seq)
+        snippet-dict (build-fn-lookup snippets)]
+    {:ns-dict ns-dict
+     :snippet-dict snippet-dict}))
+
+(defn start-docy [{:keys [exts clj role namespaces snippets]}]
   (info "starting docy .. ")
   (assert (vector? namespaces))
-  (info "starting docy namespaces: " (count namespaces))
+  (assert (vector? snippets))
+  (info "starting docy namespaces: " (count namespaces)
+        " snippets: " (count snippets))
     ;(add-discovered-namespaces this exts)
   (if clj
     (do
       (info "starting docy clj-services..")
       (expose-functions clj
                         {:name "docy"
-                         :symbols ['docy.core/build-namespaces]
+                         :symbols ['docy.core/docy-data]
                          :permission role
-                         :fixed-args [namespaces]}))
+                         :fixed-args [{:namespaces namespaces
+                                       :snippets snippets}]}))
     (warn "docy starting without clj-services, perhaps you want to pass :clj key"))
   (info "docy running!")
-  namespaces)
-
-(comment
-  (orchard/info 'missionary.core 'amb>)
-  (describe-fun 'missionary.core 'amb>)
-
-  ; deprecated should be removed
-  ; so amb and amb= should exist, but amb> should not
-  (->> (describe-ns 'missionary.core)
-       :names
-       (map :name))
-
-    (->> (describe-ns 'missionary.core)
-       :names 
-       (filter #(= "amb" (:name %)))  
-       )
-
-
-  (describe-ns 'ta.calendar.core)
-
-  (describe-ns 'ta.indicator.band)
-
-
-  (require '[modular.system])
-
-  (def d (modular.system/system :docy))
-
-  d
-
-  (build-namespaces d)
+  {:namespaces namespaces
+   :snippets snippets})
 
-
-
-  ;
-  )

src/docy/namespace.clj

@@ -0,0 +1,68 @@
+(ns docy.namespace
+  (:require
+   [orchard.info :as orchard]
+   [taoensso.timbre :refer [info warn error]]))
+
+(defn docstring [symbol]
+  (:doc (meta (resolve symbol))))
+
+(defn describe-fun [nss fun]
+  (let [data (orchard/info nss fun)]
+    (merge
+     data
+     {:ns (str (:ns data))
+      :name (str (:name data))})))
+
+(defn describe-ns [nss]
+  (require [nss])
+  (let [symbols (keys (ns-publics nss))]
+    {:ns (str nss)
+     :names (->> symbols
+                 (map #(describe-fun nss %))
+                 (filter :doc)
+                 (remove :deprecated)
+                 (sort-by :name))}))
+
+(defn build-namespaces [ns-symbol-seq]
+  (info "building namespaces: " (count ns-symbol-seq))
+  (let [r (->> (map describe-ns ns-symbol-seq)
+               (sort-by :ns)
+               ;(take 1)
+               (into []))]
+    ;(info "result: " r)
+    r))
+
+(defn ns-seq->dict [ns-seq]
+  (->> ns-seq
+       (map (fn [{:keys [ns names]}]
+              [ns names]))
+       (into {})))
+
+(comment
+  (orchard/info 'missionary.core 'amb>)
+  (describe-fun 'missionary.core 'amb>)
+
+  ; deprecated should be removed
+  ; so amb and amb= should exist, but amb> should not
+  (->> (describe-ns 'missionary.core)
+       :names
+       (map :name))
+
+  (->> (describe-ns 'missionary.core)
+       :names
+       (filter #(= "amb" (:name %))))
+
+  (describe-ns 'ta.calendar.core)
+
+  (describe-ns 'ta.indicator.band)
+
+  (require '[modular.system])
+
+  (def d (modular.system/system :docy))
+
+  d
+
+  (build-namespaces d)
+
+;
+  )