Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/borkdude/quickdoc
Quick and minimal API doc generation for Clojure
https://github.com/borkdude/quickdoc
babashka clj-kondo clojure
Last synced: about 1 month ago
JSON representation
Quick and minimal API doc generation for Clojure
- Host: GitHub
- URL: https://github.com/borkdude/quickdoc
- Owner: borkdude
- License: mit
- Created: 2022-05-05T16:25:37.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-30T14:52:59.000Z (3 months ago)
- Last Synced: 2024-11-06T10:17:52.754Z (about 1 month ago)
- Topics: babashka, clj-kondo, clojure
- Language: Clojure
- Homepage:
- Size: 74.2 KB
- Stars: 126
- Watchers: 3
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- stars - borkdude/quickdoc - Quick and minimal API doc generation for Clojure \[*MIT License*\] (⭐️126) (Clojure)
- stars - borkdude/quickdoc - Quick and minimal API doc generation for Clojure \[*MIT License*\] (⭐️126) (Clojure)
README
# Quickdoc
## API docs
See [API.md](API.md).
## Rationale
This library came out of the desire to have a fast and light weight tool that
produces API docs from any Clojure code (`.clj`, `.cljs`, `.cljc`) without
executing that code. This tool produces pure Markdown that you can read directly
on Github and the output does not need CSS or JavaScript.
Quickdoc's properties:
- Based on [clj-kondo static analysis](https://github.com/clj-kondo/clj-kondo/tree/master/analysis)
- Fast to run using [babashka](#babashka) (around 100ms for this project)
## Projects using quickdoc
- [fs](https://github.com/babashka/fs/blob/master/API.md)
- [process](https://github.com/babashka/process/blob/master/API.md)
- [quickdoc](https://github.com/borkdude/quickdoc/blob/main/API.md)
- [SCI](https://github.com/babashka/sci/blob/master/API.md)
## Status
This project is just getting started. Therefore the API may still undergo
significant changes based on early usage and feedback.
## Babashka
### task
Use as a babashka dependency and task:
``` clojure
# bb.edn
:tasks {
,,,
quickdoc {:doc "Invoke quickdoc"
:extra-deps {io.github.borkdude/quickdoc {:git/sha "7c8bef54eda28367193ec433af01bb940114f012"}}
:task (exec 'quickdoc.api/quickdoc)
:exec-args {:git/branch "master"
:github/repo "https://github.com/clj-kondo/clj-kondo"
:source-paths ["src/clj_kondo/core.clj"]}}
,,,
}
```
Now you can run `bb quickdoc` and your API docs will be generated in `API.md`.
### bbin
Install via [bbin](https://github.com/babashka/bbin):
```
bbin install io.github.borkdude/quickdoc --as quickdoc
```
## Clojure CLI
Add the following alias to your global or project-local `deps.edn`:
``` clojure
:aliases {
,,,
:quickdoc
{:deps {org.babashka/cli {:mvn/version "0.4.36"}
io.github.borkdude/quickdoc
{:deps/root "jvm"
:git/sha "7c8bef54eda28367193ec433af01bb940114f012"}}
:main-opts ["-m" "babashka.cli.exec" "quickdoc.api" "quickdoc"]}
,,,
}
```
Then you can call quickdoc using:
``` clojure
clj -M:quickdoc :github/repo https://github.com/clj-kondo :git/branch master
```
You can add default arguments to `:exec-args` in the alias:
``` clojure
:quickdoc
{,,,
:exec-args {:github/repo "https://github.com/clj-kondo"
:git/branch "master"}
```
So the command line invocation simply becomes:
``` clojure
clj -M:quickdoc
```
## Clojure tool
Quickdoc is also available as a [clj
tool](https://clojure.org/reference/deps_and_cli#_tool_usage). Note that this
way of invoking quickdoc is slower to start than with babashka.
To install, run:
```
clj -Ttools install io.github.borkdude/quickdoc '{:deps/root "jvm" :git/sha ""}' :as quickdoc
```
Then invoke quickdoc using:
```
clj -Tquickdoc quickdoc '{:github/repo "https://github.com/borkdude/quickdoc"}'
```
## Can it be improved to do ...?
Probably yes! Let me know in [Github Discussions](https://github.com/borkdude/quickdoc/discussions) or create an [issue](https://github.com/borkdude/quickdoc/issues).
## License
See [LICENSE](LICENSE).