Up to now the generation of documentation out of javaScript sources don’t seem to have a standard tool.

I’ve tried yuidoc and have to say that I’m not complete convinced. The pros and cons of yuidoc are a story for itself.

However I’ve worked out a (conceptual) way which combines my daily tools couchdb couchapp and git for having the latest documentation (generated by yuidoc) online and moreover offline.

Install yuidoc

There are official repos on opensuse.com providing the python stuff. With this the installation goes like described in the INSTALL file after extracting the zip:

 1. Check to see if setuptools is installed.
     Execute this command:
         which easy_install

     If it returns something, it's installed skip to step #3.


 2. Install Setup Tools:
     Extract the archive in ext and install the package
     sudo python setup.py install (no sudo needed for cygwin or windows)

     setuptools
         cd ext
         tar xfvz setuptools-0.6c9.tar.gz
         cd setuptools-0.6c9
         sudo python setup.py install

 3. Install the dependencies

     easy_install pygments
     easy_install Cheetah
     easy_install simplejson


 4. Make a copy of yuidoc/bin/example.sh and modify the paths to suit your
 needs.

If you speak a lang with strange letters (öäü) you should replace line 57 in yuidoc_highlight.py with:

out.writelines(highlighted.encode('utf-8'))

Config

The example.sh from point 4 is the script you have to modify and execute. This is nice, since you can simply use the script as post commit hook

cp  yuidoc/bin/example.sh  ~/..project../.git/post-commit

You can set some variables in that script e.g.:

version=`git log --pretty=format:"%ad-%an-%H" --date=short -n 1`

to display some version information on the page.

Use a couchapp!

I have to document a couchapp I wrote. Here, my first attempt was: make a folder below _attachments and let the html arise in there failed. Rewriting the

 yuidoc/template/main.tmpl

to adapt the server pathes is simply to much work. Therefore this idea:

• Generate a couchapp project-doc and strip it down to the bones:

  /dir> ls project-doc/
       ./
       ../
       _attachments/
       .couchappignore
       couchapp.json
       .couchapprc*
       _id
  

• set the variables in the shell/hook-script to

   parser_in="./_attachments/js-src-to-doc"
   parser_out=$doc_home/_attachments
   generator_out=$doc_home/_attachments
  

while

     doc_home=path/to/project-doc

• couchapp push
• visit http://localhost:5984/db_name/_design/project-doc/index.html

Also the deployment can be activated via the shell/hook-script. Add

cd path/to/project-doc && couchapp push

at the last line. If everything works fine you got a fresh source code documentation on every commit.

After hs in config hell this:

    Alias /git /srv/www/htdocs/git
 <Directory /srv/www/htdocs/git>
     Options ExecCGI  Indexes  +FollowSymLinks
     AddHandler cgi-script cgi
     DirectoryIndex gitweb.cgi
     RewriteEngine On
     RewriteCond %{REQUEST_FILENAME} !-f
     RewriteCond %{REQUEST_FILENAME} !-d
     RewriteRule ^.* /git/gitweb.cgi/$0 [L,PT]
 </Directory>

works for me placed in a gitweb.conf below

/etc/apache2/cond.d

Do so if you want to provide git (bare) repos over apache …

Don’t forget to

 touch git-daemon-export-ok

otherwise you will get a 404 No- projects found. Also execute

git update-server-info

and enable the sample post-update hook

the markdown format (e.g. used at github.com) can be converted to html using:

 perl Markdown.pl --html4tags ../map/README.md > ../map/index.html

the src for the perl script can be downloaded at http://daringfireball.net/projects/markdown/

wherenow-org:

Git rebase, it really is rather awesome. 

(Source: saundershugh)

(via nondeterminism)

euforic:

In this post I present the development model that I’ve introduced for all of my projects (both at work and private) about a year ago, and which has turned out to be very successful. I’ve been meaning to write about it for a while now, but I’ve never really found the time to do so thoroughly, until now. I won’t talk about any of the projects’ details, merely about the branching strategy and release management.

It focuses around Git as the tool for the versioning of all of our source code.

Read More

(via euforic)

“Tig ist ein Programm zum Durchstöbern von git-Repositorien, das zusätzlich zur seitenweisen Anzeige der Ausgabe verschiedener git-Kommandos dienen kann. Beim Durchstöbern von Verzeichnissen verwendet es die zugrundeliegenden git-Kommandos, um verschiedene Ansichten anzuzeigen, darunter das zusammengefasste Revisionslog und eine Änderung mit der Logmeldung, diffstat und dem diff selbst. Wenn es für die seitenweise Anzeige eingesetzt wird, nimmt es die Eingaben von der Standardeingabe und hebt sie farblich hervor.”

http://jonas.nitro.dk/tig/manual.html