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