Documentation/generating documentation
- Dominant language
- Clojure
- Stars
- 558
- Forks
- 56
- PR merge metrics
- No merged PRs in 30d
Description
Usually my first step in understanding a new codebase is to write documentation for it :-)
I've been experimenting with integrating [Codox](https://github.com/weavejester/codox) and haven't yet found a satisfactory way to proceed. I'm raising this now because if you feel there is a better way to generate documentation I'd prefer to work on that, but if you agree that Codox is the right way to proceed I'll keep worrying at this until I do make it work.
Adding codox to the root `deps.edn` thus
```clojure
:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
:exec-fn codox.main/generate-docs
:exec-args {:source-paths ["libs/kit-core/src" ;; "libs/kit-generator/src" "libs/kit-hato/src"
]}}
```
feels like the right way to go because it would produce a single linked web of documentation, but I haven't (yet) made it work - it fails with multiple errors of the general form:
```
(base) simon@mason:~/workspace/kit$ clojure -X:codox
Could not generate clojure documentation for kit.config - root cause: java.io.FileNotFoundException Could not locate kit/config__init.class, kit/config.clj or kit/config.cljc on classpath.
java.io.FileNotFoundException: Could not locate kit/config__init.class, kit/config.clj or kit/config.cljc on classpath.
```
Adding codox thus to the `deps.edn` of individual libraries does work, but, of course, generates isolated documentation webs for the individual libraries instead of a single integrated web:
```clojure
:aliases {:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
:exec-fn codox.main/generate-docs
:exec-args {:source-paths ["src"]}}}
```
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the root deps.edn and the individual libraries' deps.edn files, then run the documented clojure -X:codox command to reproduce the classpath errors. Compare the working per-library Codox configuration with the root configuration. Done means Codox generates one integrated, linked documentation web for the libraries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- clojure
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100