ben-x9 / cljs-api-docs

ClojureScript API and Syntax Documentation

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ClojureScript API Docs Builder

[](https://travis-ci.org/cljsinfo/cljs-api-docs) __[📖 Latest API Documentation](https://github.com/cljsinfo/cljs-api-docs/blob/catalog/INDEX.md)__

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

overview


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

parse-output

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

screenshot

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.

    user-contributed

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

ezoic increase your site revenue

About

ClojureScript API and Syntax Documentation

License:MIT License


Languages

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