Manual install for the DTK API documentation tool
- PHP 5.2 or higher
- Apache with mod_rewrite enabled
Generating the documentation and running API viewer locally
get latest Node.js from http://nodejs.org/#download
check out js-doc-parse from bill (it has various fixes/enhancements needed for the viewer):
$ git clone --recursive https://github.com/wkeese/js-doc-parse.git $ cd js-doc-parse $ git checkout 1.0
edit config.js to give path to dojo (your path may vary from example below):
- run parser on
$ ./parse.sh config=./config.js
C:\> parse.bat config=./config.js
This will generate
- check out api-viewer
Check out this project into a directory called "api", under your web root, so that it's accessible via http://localhost/api:
$ cd your web root $ git clone firstname.lastname@example.org:wkeese/api-viewer.git api
If you put it in a different location instead, then you need to update config.php and .htaccess to point to the other location.
- move files to data directory
api_data/1.9 directory (or whatever the current version is), as a sibling of the api directory,
and move the
tree.json from the step #4 above to that directory.
Alternately, you can set the directory to somewhere else by editing config.php.
Instructions to run the site
Create a virtual host in Apache, and allow Overrides in the definition.
Place the entire API site in the directory where you are pointing the vhost.
Set the permissions on the /data directory to be writable; it should have the ability to not only write directly to that directory, but to also create sub-directories and write to them as well. To do this on Mac OS X:
$ chmod -R +a 'user:_www allow delete,list,search,add_file,add_subdirectory,read,write' data
Open the config.php file, and edit with your specific information (including the
_base_urlvariable; leave this to be
/if you are running in the root of a vhost). Note that modules to be displayed should all have a value of
-1(this is set by the class tree generator), and should be in the order in which you want the modules to appear within the class tree.
If you are just running the site with the included XML files, that should be all there is to running the site; just hit your vhost and go.
Theming your API documentation tool
Themes are located in in the
themes directory. The require, at a minimum:
- theme.css - Includes any CSS styling that needs to be included in the doucment
- index.php - The content is used to populate the Welcome tab of the API Viewer
- header.php - Inserted before the main content area
- footer.php - Inserted after the main content area
These files will be included as the pages are generated.
- generate.php - utility methods
- item.php - generates documentation for one module, i.e. the content of one tab
The data files are:
- details.xml - main information about modules
- tree.json - just the metadata needed to display the tree of modules