ClojureScript API Docs Builder

[](https://travis-ci.org/cljsinfo/cljs-api-docs)

__[📖 Latest API Documentation](https://github.com/cljsinfo/cljs-api-docs/tree/catalog)__

Hello! We are building a ClojureScript website. A section of this website will be devoted to providing beautiful and informative documentation for the core syntax, library and compiler. This repo provides the means to generate this documentation.

📄 Doc page sample
🌱 How to contribute docs

Table of Contents

1. Published API
2. API Generator
3. Offline Docs

Published API

The API docs are published to the catalog branch. It contains version tags for locating the API reference for specific versions of ClojureScript. You can use the history table to navigate the version tags.

The catalog branch has each of the generated files for exploring/using the API reference:

* see format details at cljs-api-format.edn

Pseudo-namespaces?

To help categorization of special case symbols that do not have a namespace, we just invent some "psuedo-namespaces":

• special - special forms
• specialrepl - REPL special forms
• syntax - syntax forms (we think these deserve API docs too)

API Generator

The API generator parses info from the ClojureScript repo and merges it with the manual docs.

This will generate docs for the latest version of ClojureScript and output them to the catalog/ folder:

$ lein run

The generator has to parse the previous versions of ClojureScript to understand the symbol history (takes about 5-10 minutes), but they will be cached for much faster subsequent runs (~10 seconds).

Use Grip to preview the docs:

$ grip catalog
 * Running on http://localhost:5000/ (Press CTRL+C to quit)

Advanced

The generator can take an optional map at the command line. Use this to target a specific version (i.e. one of ClojureScript's tag):

$ lein run '{:version "r3211"}'

Or target the master branch:

$ lein run '{:version :master}'

Or generate the catalog branch containing pages for every version:

$ lein run '{:catalog? true      ;; Create a git repo catalog w/ doc commits for each cljs version.
             :skip-pages? false  ;; Don't skip generating the docs pages for previous versions.
            }'

Full table of options:

Implementation

To build the API reference, we are doing self-analysis of literal forms created from tools.reader rather than using tools.analyzer. We may use the helpful wrapper codox if this becomes insufficient.

Here is sample output of the parser to get an idea of the types of things we parse:

These are the source files concerned with the API reference generator:

These are the mustache templates that we use to render the catalog files.

👍 I use Grip to preview the rendered github-flavored markdown.

Offline docset for Dash

This is an offline ClojureScript API docset that can be read by the following apps:

• Dash for Mac
• Zeal for Linux/Windows
• Velocity for Windows

There are two options for getting the docset:

1. Manual: Download ClojureScript.docset from latest release.

2. Auto: Search "ClojureScript" in User-Contributed in Dash. This docset will auto-update.

   

Generating

This is currently a strange setup for making offline versions of GitHub's rendered markdown pages for our API catalog. This is expected to be temporary while we work on better designed docs with usage examples, cross-refs, etc.

The process for creating this is documented in the commands below

# Go to docset working directory.
$ cd docset

# Download latest catalog HTML files from github.
# (Requires httrack.)
$ ./download-pages.sh

# Format pages to isolate the markdown views,
# and correct a few other things.
# (Requires phantomjs.)
$ ./format-pages.js

# Build docset for Dash.
# (errors will tell if you something isn't setup correctly)
$ cd ..
$ lein run '{:task :docset}'

# Prepare a Pull Request commit to update published docset.
# (manual update steps will be printed)
$ script/docset-pr.sh

License

MIT, Copyright © 2014-2015 Shaun LeBron