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)

Published API
API Generator
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
`INDEX.md`	an overview of the API with reference tables
`refs/*.md`	dedicated view for a specific API symbol
`HISTORY.md`	table of all versions and their changes
`UNPORTED.md`	list of symbols that are not ported from Clojure
`UNFINISHED.md`	table of symbols that have unfinished manual docs

* 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.

⚠️	##### Case-Sensitive file system required! Example: `cljs.core_cons.md` and `cljs.core_Cons.md` 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}'

Advanced

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`

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:

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
`index.md`	API overview page
`syntax.md`	Syntax overview page
`library.md`	Library API page
`compiler.md`	Compiler API page
`ns.md`	per Namespace page
`var.md`	per Var page
`special-ns.md`	per Special Forms category page
`history.md`	version history and changes
`unported.md`	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:

Manual: Download ClojureScript.docset from latest release.
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

pbzdyl/cljs-api-docs