-
Notifications
You must be signed in to change notification settings - Fork 182
Generating Brackets API Docs
This set of commands creates the Brackets API Docs to be published at http://brackets.io/docs. So far, the only set of docs are for the current version of Brackets, but it would probably be useful to provide snapshots of docs for major releases (e.g. Brackets 1.0).
Brackets API Documents are generated using apify which is an open source project was written by Brackets committer Chema Balsas. The content is based on JSDoc Annotations in Brackets source code which follow Google Closure Compiler.
Note: There is a known bug that the incorrect folder structure and links are generated on Windows, so use Mac to generate documents until that bug is fixed.
The following commands assume that the brackets and brackets.io root folders are side-by-side.
This command installs the node apify package globally so you can run it from any folder. Note that apify is still being developed, so it's a good idea to re-run this command each time to get the latest package.
cd ~
sudo npm install -g jsdocify
Brackets API documents are posted to the https://github.com/brackets-cont/brackets.io repo, so clone that repo (first time only):
git clone https://github.com/brackets-cont/brackets.io.git
cd brackets.io
Create a new branch off of latest gh-pages branch (default branch in brackets.io).
git checkout gh-pages
git pull
git status
git checkout -b yourname/new-branch-name
Checkout the Brackets branch that you want to generate API Docs for which is usually release branch. Currently, we only generate docs for the current master, but once we reach version 1.0, we'll want to generate docs for each major and minor release.
cd ../brackets
git checkout release
git pull
git status
The source folder (-s) for API Docs is the brackets/src folder. The following command assumes that you are in the root of the brackets repo.
The output folder (-o) is brackets.io/docs/current.
The title (-t) is Brackets.
apify -s src/ -o ../brackets.io/docs/current -t Brackets
The API Docs should now be in the brackets.io repo in your new branch, so you'll need to submit a pull request and then merge files.