kit-clj / kit-clj/kit

Documentation/generating documentation

Open
#7 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.