diff --git a/lib/cli.janet b/lib/cli.janet index 86a29ae..cc9e3cd 100644 --- a/lib/cli.janet +++ b/lib/cli.janet @@ -15,6 +15,10 @@ :proxy "url" :help "Use as prefix for source code links."} "-------------------------------------------" + "--only" {:kind :multi + :short "O" + :proxy "path" + :help "Only create entries for bindings in 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")) diff --git a/lib/documentarian.janet b/lib/documentarian.janet index b8ec86d..976fa39 100644 --- a/lib/documentarian.janet +++ b/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])] diff --git a/test/documentarian.janet b/test/documentarian.janet index de336c1..28956e6 100644 --- a/test/documentarian.janet +++ b/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)]