ben-x9 / cljs-api-docs

ClojureScript API and Syntax Documentation

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ClojureScript API Docs Builder

[]( __[📖 Latest API Documentation](

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


Git Branch Description
master API generator and manual docs
catalog API release (force-pushed)

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:

Catalog File Description
cljs-api.edn* a data structure containing all API information an overview of the API with reference tables
refs/*.md dedicated view for a specific API symbol table of all versions and their changes list of symbols that are not ported from Clojure table of symbols that have unfinished manual docs

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


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.

⚠️ ##### Case-Sensitive file system required!

Example: and must represent different pages. See Issue #48 for Mac solution.

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)

Watch/auto-compile cljsdoc changes with the following:

$ lein run '{:watch? true}'


The generator can take an optional map at the command line. Use this to target a specific version or tag.

$ lein run '{:version "0.0-3211"}'

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:

option description e.g. default
:task a side task to run instead of the main one :docset :cljsdoc nil
:version version to process "<tag>" :latest :master :latest
:catalog? create a catalog repo? true false false
:skip-pages? skip page-creation for previous versions? true false true
:skip-parse? skip parsing versions if already cached? true false true
:watch? watch and recompile cljsdoc changes true false false
:new-release force recognize new version (because maven api can be slow) "1.7.10" nil


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:

Source File Description
core.clj main entry
catalog.clj builds the API catalog of docs for release
clojure_api.clj retrieves original clojure api info to correlate with cljs
config.clj filename constants and dynamic vars for output directories
docset.clj generates the offline docset for Dash
docstring.clj helpers for extracting/formatting/removing docstrings
encode.clj encoding scheme to create filenames for symbols
parse.clj parse namespaces for their symbols
syntax.clj all data related to syntax forms
read.clj read forms from namespaces
repo_cljs.clj helpers for traversing official Clojure and ClojureScript repos
result.clj transforms parsed data into a final result structure
display.clj creates titles for pseudo-symbols and sorts them by namespace.
write.clj writes all output files for the data created by result.clj
util.clj miscellaneous functions

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

Template File Description API overview page Syntax overview page Library API page Compiler API page per Namespace page per Var page per Special Forms category page version history and changes table of symbols not ported from clojure

👍 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:

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.



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.)
$ ./

# 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/


MIT, Copyright © 2014-2015 Shaun LeBron

ezoic increase your site revenue


ClojureScript API and Syntax Documentation

License:MIT License


Language:Clojure 92.0%Language:Ruby 5.3%Language:Shell 1.4%Language:JavaScript 1.3%