Support limiting files with --only option

lib/cli.janet

@@ -15,6 +15,10 @@
                             :proxy "url"
                             :help  "Use <url> as prefix for source code links."}
            "-------------------------------------------"
+           "--only"        {:kind  :multi
+                            :short "O"
+                            :proxy "path"
+                            :help  "Only create entries for bindings in <path> in the API document."}
            "--exclude"     {:kind  :multi
                             :short "x"
                             :proxy "path"
@@ -61,6 +65,7 @@
     :exclude (get-in args [:opts "exclude"] [])
     :include-private? (get-in args [:opts "private"] false)
     :link-prefix (get-in args [:opts "link-prefix"] "")
+    :only (get-in args [:opts "only"])
     :output-file (get-in args [:opts "out"] "api.md")
     :project-file (get-in args [:opts "project"] "project.janet")
     :modpath (when modpath (string modpath doc/sep "lib"))

lib/documentarian.janet

@@ -16,7 +16,9 @@
 
   {{/project-doc}}
   {{#modules}}
+  {{#ns}}
   ## {{ns}}
+  {{/ns}}
 
   {{#items}}{{^first}}, {{/first}}[{{name}}](#{{in-link}}){{/items}}
 
@@ -99,16 +101,13 @@
       (string file "#L" line))))
 
 
-(def- headings @{})
-
-
 (defn- in-link
   ```
   Creates an internal link
 
   ```
   # Uses the algorithm at https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb
-  [name]
+  [name headings]
   (def key (-> (peg/match ~{:main    (% (any (+ :kept :changed :ignored)))
                             :kept    (<- (+ :w+ (set "_-")))
                             :changed (/ (<- " ") "-")
@@ -138,7 +137,7 @@
                        (string/format "%q" (item :value))))
    :docstring (item :docstring)
    :link      (link item (opts :project-root) (opts :link-prefix))
-   :in-link   (in-link (item :name))})
+   :in-link   (in-link (item :name) (opts :headings))})
 
 
 (defn- bindings->modules
@@ -153,10 +152,11 @@
   (var first? false)
   (loop [i :range [0 (length bindings)]
            :let [binding (get bindings i)]]
-    (if (= curr-ns (binding :ns))
+    (def ns (if (= "" (binding :ns)) false (binding :ns)))
+    (if (= curr-ns ns)
       (set first? false)
       (do
-        (set curr-ns (binding :ns))
+        (set curr-ns ns)
         (set items @[])
         (set module @{:ns curr-ns :items items})
         (set first? true)
@@ -175,6 +175,7 @@
   (def template (if (opts :template-file)
                   (slurp (opts :template-file))
                   default-template))
+  (put opts :headings @{})
   (musty/render template {:project-name (project :name)
                           :project-doc  (project :doc)
                           :modules      (bindings->modules bindings opts)}))
@@ -291,7 +292,8 @@
           (array/push bindings {:ns ns :doc meta})
 
           (one? (length meta)) # Only aliased bindings should have a meta length of 1
-          nil
+          (->> (binding-details name (table/getproto meta) ns)
+               (array/push bindings))
 
           (->> (ns-or-alias name ns)
                (binding-details name meta)
@@ -321,21 +323,21 @@
   ```
   Replaces mixture of files and directories with files
   ```
-  [paths &opt parent exclusions]
+  [paths &opt parent excludes]
   (default parent (string "." sep))
-  (default exclusions [])
+  (default excludes [])
   (mapcat (fn [path]
             (def full-path (string parent path))
             (def kind (os/stat full-path :mode))
             (cond
-              (find (fn [x] (string/has-prefix? x full-path)) exclusions)
+              (find (fn [x] (string/has-prefix? x full-path)) excludes)
               []
 
               (= :file kind)
               full-path
 
               (= :directory kind)
-              (gather-files (os/dir full-path) (string full-path sep) exclusions)))
+              (gather-files (os/dir full-path) (string full-path sep) excludes)))
           paths))
 
 
@@ -393,8 +395,8 @@
 
   (def envs @{})
   (when-let [sources (get-in project-data [:source :source])]
-    (def exclusions (map (fn [x] (string project-root x)) (opts :exclude)))
-    (def paths (gather-files sources project-root exclusions))
+    (def excludes (map (fn [x] (string project-root x)) (opts :exclude)))
+    (def paths (gather-files (or (opts :only) sources) project-root excludes))
     (reduce (fn [e p] (merge-into e (extract-env p))) envs paths))
 
   (when-let [name (get-in project-data [:native :name])]

test/documentarian.janet

@@ -98,8 +98,8 @@
   (def expect
     (string "# Example API\n\n"
             "## example\n\n"
-            "[example](#example-1), "
-            "[example*](#example-2), "
+            "[example](#example), "
+            "[example*](#example-1), "
             "[example2](#example2)\n\n"
             "## example\n\n"
             "**function**  | [source][1]\n\n\n"
@@ -117,7 +117,7 @@
     [{:name 'example :ns "example" :kind :function :docstring "This is an example." :file "example.janet" :line 1}
      {:name 'example* :ns "example" :kind :function :docstring "This is an example." :file "example.janet" :line 2}
      {:name 'example2 :ns "example" :kind :function :docstring "This is an example." :file "example.janet" :line 3}])
-  (def actual (doc/emit-markdown bindings {:name "Example"} {}))
+  (def actual (doc/emit-markdown bindings {:name "Example"} @{}))
   (is (== expect actual)))
 
 
@@ -134,7 +134,7 @@
     [{:name 'example :ns "example" :kind :function :docstring sample-docstring}
      {:name :doc :ns "example" :kind :string :doc sample-docstring}])
 
-  (let [lines (->> (doc/emit-markdown bindings {:name "Example" :doc sample-docstring} {})
+  (let [lines (->> (doc/emit-markdown bindings {:name "Example" :doc sample-docstring} @{})
                    (string/split "\n"))
         [project-docstring mod-docstring fn-docstring] (filter (partial string/find "sample") lines)
         [project-code-block mod-code-block fn-code-block] (filter (partial string/find "fenced") lines)]