prototype-doc-workflow.txt

#####
## INITIAL CONFIGURATION
#####

# Fork sstephenson/prototype on GitHub
# Go to this url and click the fork button. This will create a prototype 
# repository under your GitHub account.

http://github.com/sstephenson/prototype

# Clone your fork to a local directory.
# I put it in my OSX apache path so that I can view it via
# http:/localhost/~dand/prototype:

cd ~/Sites
git clone [email protected]:{ ... your github username ... }/prototype.git
cd prototype
# example: git clone [email protected]:dandean/prototype.git

# Add the prototype documentation branch as a remote on your prototype repo.
# The documentation branch is maintained by samleb:

git remote add -t documentation samleb git://github.com/samleb/prototype.git

# Pull samleb docs repo down

git fetch samleb

# Branch samleb docs off to your own documentation branch
# This version will always match the official documentation branch,
# you will not work on it directly, but _branch it_ and work on that:

git checkout --track -b documentation samleb/documentation

#####
## FOR EACH TICKET
#####

# Make sure you are on _your_ documentation branch.
# You can always verify this by calling `git branch`. The one with the `*` in
# front of it is the repository that you're currently on.

git checkout -b port_{ ... my ticket ... }_{ ... ticket number ... } documentation
# example: git checkout -b port_dollar_111 documentation


# Claim a ticket in lighthouse
# Work on the ticket ...
# Build the pdoc docs with rake to make sure you didn't break anything:

rake doc

# OR, build just a section (dom, ajax, lang, etc)

rake doc SECTION=dom

# Commit your changes to your doc branch.
# Replace the content within and including the curly braces with
# real information:

git add path/to/file.js
git comment -m 'doc: {... ticket name ...} [#{...ticket number...} state:fixed_in_branch]'
# example: git comment -m 'doc: Merge/update old $ docs into the source [#111 state:fixed_in_branch]'

# Push your committed changes to _your_ patches remote repo on GitHub:

git push origin port_{ ... my ticket ... }_{ ... ticket number ... }
# example: git push origin port_dollar_111

# Update the lighthouse ticket. Remove "committed" tag, add "patched" tag
# and paste in the link to your commit on GitHub.

# Go back to samleb docs and pull the latest to make sure you're still up to date.

git checkout documentation
git pull samleb

# Find another ticket to work on.

#############################################
# GENERAL CONSIDERATIONS AND CONVERSIONS
#############################################

# HTML Entities should get converted back to actual html characters:

&gt;a&lt  -->  <a>

Any and all references to things documented in the source should get
wrapped in double-square-brackets [[]] instead of backticks.

`Ajax.Request` --> [[Ajax.Request]]

All headlines should use Markdown H5 declarations:

<h5>Headline</h5>  --> ##### Headline
### Headline>  --> ##### Headline

# Side notes:

* It isn't yet possible to include images in your documentation.
* It won't ever be possible to include live html examples in pdoc docs.