# Which libraries are in need of accessible API docs?

**URL:** https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109
**Category:** Community Building
**Created:** [December 6, 2017, 10:06am UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109 "2017-12-06T10:06:25Z")
**Posts on this page:** 8
**Page:** 1

<div class="post-metadata">

### Author: ![plexus](https://clojureverse.org/user_avatar/clojureverse.org/plexus/32/6_2.png) [@plexus](https://clojureverse.org/u/plexus)
#### Post date: [December 6, 2017, 10:06am UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/1 "2017-12-06T10:06:26Z")

</div>

I was looking at [Enlive](https://github.com/cgrand/enlive/) (see also [Best library for querying HTML?](https://v2.clojureverse.org/t/best-library-for-querying-html/1103/3)), which I’ve used in the past and actually quite like, but then realized that I couldn’t find any up-to-date API docs anywhere. Certainly not linked from the project. There’s even a [4 year old issue](https://github.com/cgrand/enlive/issues/84) about the lack of docs, with no resolution.

Apparently [clojuredocs.org](http://clojuredocs.org) used to host API docs for libraries, but now it seems to only do core.

The thing is though, if you have your library on Github then it’s extremely easy to just host API docs youreslf, using [codox](https://github.com/weavejester/codox) and this script:

> **Show generate\_docs script**
>
> ```auto
> #!/bin/bash
> 
> # Keep a separate branch of generated API docs.
> #
> # This script generates API documentation, commits it to a separate branch, and
> # pushes it upstream. It does this without actually checking out the branch,
> # using a separate working tree directory, so without any disruption to your
> # current working tree. You can have local file modifications, but the git index
> # (staging area) must be clean.
> 
> # The git remote to fetch and push to. Also used to find the parent commit.
> TARGET_REMOTE="origin"
> 
> # Branch name to commit and push to
> TARGET_BRANCH="gh-pages"
> 
> # Command that generates the API docs
> DOC_CMD="lein with-profile +codox codox"
> 
> # Working tree directory. The output of $DOC_CMD must end up in this directory.
> WORK_TREE="gh-pages"
> 
> if ! git diff-index --quiet --cached HEAD ; then
> echo "Git index isn't clean. Make sure you have no staged changes. (try 'git reset .')"
> exit
> fi
> 
> git fetch $TARGET_REMOTE
> rm -rf $WORK_TREE
> mkdir -p $WORK_TREE
> 
> echo "Generating docs"
> $DOC_CMD
> 
> echo "Adding file to git index"
> git --work-tree=$WORK_TREE add -A
> 
> TREE=`git write-tree`
> echo "Created git tree $TREE"
> 
> if git show-ref --quiet --verify "refs/remotes/${TARGET_REMOTE}/${TARGET_BRANCH}" ; then
> PARENT=`git rev-parse ${TARGET_REMOTE}/${TARGET_BRANCH}`
> echo "Creating commit with parent ${PARENT} ${TARGET_REMOTE}/${TARGET_BRANCH}"
> COMMIT=`git commit-tree -p $PARENT $TREE -m 'Updating docs'`
> else
> echo "Creating first commit of the branch"
> COMMIT=`git commit-tree $TREE -m 'Updating docs'`
> fi
> 
> echo "Commit $COMMIT"
> echo "Pushing to $TARGET_BRANCH"
> 
> git reset .
> git push $TARGET_REMOTE $COMMIT:refs/heads/$TARGET_BRANCH
> git fetch
> echo
> git log -1 --stat $TARGET_REMOTE/$TARGET_BRANCH
> 
> ```

Copy the script to the root of your project, and in your project.clj configure Codox (for boot just update the `DOC_CMD` in the script).

```auto
(defproject ,,,
  ,,,
  :profiles {:codox {:plugins [[lein-codox "0.10.3"]]
                     :codox {:project {:name "my-project"}
                             :doc-paths ["doc"]
                             :output-path "gh-pages"}}}
  )

```

That’s it. Now when you run `./generate_docs` it will run codox, create a new commit on the `gh-pages` branch, and push it to Github. The script is designed to be super robust. It uses lower level Git operations so it doesn’t have to mess with your current branch, switch branches, or change the working tree. It really should just work. Your docs will be available at `https://<username>.github.io/<projectname>`. Don’t forget to link to them from your README.

You can add extra Markdown files which become part of the generated site, which is really great feature for adding e.g. a getting started guide or more reference material, and there are several themes available to adjust the look of Codox to your taste.

Here are some examples

- [Sparkledriver](https://jackrusher.github.io/sparkledriver/)
- [Lambdaisland/uri](https://lambdaisland.github.io/uri/)
- [Enlive](http://plexus.github.io/enlive/)

I created a PR to add this to Enlive, I hope Christophe accepts it.

Now my question is: which other projects could really benefit from this? Who else should I send a PR to?

---

<div class="post-metadata">

### Author: ![martinklepsch](https://clojureverse.org/user_avatar/clojureverse.org/martinklepsch/32/80_2.png) [@martinklepsch](https://clojureverse.org/u/martinklepsch)
#### Post date: [December 6, 2017, 5:00pm UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/2 "2017-12-06T17:00:30Z")

</div>

A few that come to mind (disclaimer: some are my own 😇):

- [https://github.com/juxt/tick](https://github.com/juxt/tick)
- [https://github.com/confetti-clj/s3-deploy](https://github.com/confetti-clj/s3-deploy)
- [https://github.com/martinklepsch/derivatives](https://github.com/martinklepsch/derivatives)

---

<div class="post-metadata">

### Author: ![plexus](https://clojureverse.org/user_avatar/clojureverse.org/plexus/32/6_2.png) [@plexus](https://clojureverse.org/u/plexus)
#### Post date: [December 7, 2017, 9:59am UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/3 "2017-12-07T09:59:18Z")

</div>

I opened issues for tick and s3-deploy, and created a PR for derivatives.

With that there’s now also an [example of using boot with generate\_docs](https://github.com/martinklepsch/derivatives/pull/15). It’s pretty straightforward still, just add codox in your build.boot, and update the DOC\_CMD and WORK\_TREE variables in the script like so

```auto
# Command that generates the API docs
DOC_CMD="boot codox -n derivatives -o gh-pages -s src target"

# Working tree directory. The output of $DOC_CMD must end up in this directory.
WORK_TREE="target/gh-pages"

```

---

<div class="post-metadata">

### Author: ![plexus](https://clojureverse.org/user_avatar/clojureverse.org/plexus/32/6_2.png) [@plexus](https://clojureverse.org/u/plexus)
#### Post date: [December 7, 2017, 11:51am UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/4 "2017-12-07T11:51:19Z")

</div>

As part of adding the script to Derivatives Martin and I made several improvements, the current version is now here

> <https://gist.github.com/plexus/45b014b3fc218cee6965b12c52e58b8d>

Some improvements

- You can specify some of the variables from the command line, instead of always having to change the script
- The commit message on the gh-pages branch shows the state of your repo, so you know which code you actually generated docs for
- if there is no change in output then it won’t create and push an empty commit, instead it shows a warning
- Added a lot more comments since some of this stuff is pretty arcane

I’ve turned it into a Gist so I can push updates if needed. In the long run we’ll need a better way to distribute this so people can more easily upgrade. Maybe it should actually be a lein/boot package? Or something something npm?

Of course even better would be a public service that can generate and host these docs for multiple libraries across multiple versions, but I personally have enough going on right now to start on that 🙂

---

<div class="post-metadata">

### Author: ![martinklepsch](https://clojureverse.org/user_avatar/clojureverse.org/martinklepsch/32/80_2.png) [@martinklepsch](https://clojureverse.org/u/martinklepsch)
#### Post date: [December 7, 2017, 11:59am UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/5 "2017-12-07T11:59:57Z")

</div>

That’s awesome, thanks Arne! ❤

So here are the brand-new [derivatives docs](https://martinklepsch.github.io/derivatives/). It’s interesting to see this come together in this form. Makes it quite a bit easier to see where documentation could be improved.

> Of course even better would be a public service that can generate and host these docs for multiple libraries across multiple versions, but I personally have enough going on right now to start on that 🙂

I think that’s a very cool idea. I also have a bunch of other things in my queue but I believe that this could become a thing. I’m sure if such project came to be hosting would be a solvable issue as well. So many cool things to do… 🙀

---

<div class="post-metadata">

### Author: ![plexus](https://clojureverse.org/user_avatar/clojureverse.org/plexus/32/6_2.png) [@plexus](https://clojureverse.org/u/plexus)
#### Post date: [December 11, 2017, 8:15pm UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/6 "2017-12-11T20:15:55Z")

</div>

I just keep seeing more uses for this, like I want to have some org-mode files, and always have the latest HTML version on-line as well. So far I’ve been copying this script from repo to repo, but it keeps improving, so I finally gave it a proper home. I tweaked it a bit more, and now it’s called `autodoc` (monospace font for the name is part of the branding :-P)

> **[GitHub - plexus/autodoc: Automate the publishing of generated docs](https://github.com/plexus/autodoc)**
>
> Automate the publishing of generated docs. Contribute to plexus/autodoc development by creating an account on GitHub.

With this you can simply put this in your repo

```auto
#!/bin/bash
export AUTODOC_CMD="lein codox"
\curl -sSL https://raw.githubusercontent.com/plexus/autodoc/master/autodoc.sh | bash

```

You like? I like!

---

<div class="post-metadata">

### Author: ![plexus](https://clojureverse.org/user_avatar/clojureverse.org/plexus/32/6_2.png) [@plexus](https://clojureverse.org/u/plexus)
#### Post date: [December 12, 2017, 6:57pm UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/7 "2017-12-12T18:57:01Z")

</div>

And… now it’s self-hosted. Converted the README to org-mode so I can convert it to HTML with emacs.

Result: [autodoc](https://plexus.github.io/autodoc/)

Also made the output a bit nicer, added a version number and CHANGELOG, added some more checks so that if warns you if something seems out of whack, like the DOC command not creating any output.

 ![2017-12-12-194823_1548x563_scrot](https://clojureverse.org/uploads/default/original/1X/df588e0db80cf36157f9e888e32d3e9700ac2db1.png)

---

<div class="post-metadata">

### Author: ![system](https://clojureverse.org/uploads/default/original/2X/5/51079bf9e4b7d9466242c06cf1e43b9f8bd6da14.png) [@system](https://clojureverse.org/u/system)
#### Post date: [October 5, 2018, 12:50pm UTC](https://clojureverse.org/t/which-libraries-are-in-need-of-accessible-api-docs/1109/8 "2018-10-05T12:50:39Z")

</div>