documental v0.3.10

Please Note: This is currently a work in progress !

Documental is a build tool to automatically generate a documentation site from your javascript source code. The aim of documental was not only to allow for easy generation of docs for functions that have them but to also expose the functions that do not have documentation and provide an easy way of searching and navigating at the same time.

Contents

1. Usage
2. Development
3. Angular App

Nuts & Bolts

The project is made up of two ( separable ) parts;

1. The node module
2. The angular ( 1.4.7 ) app

Node Module

Documental uses JSDoc as the standard for identifying documentation comments ( comments preceeding a function that begin with /** ) These comment are found and parsed by creating a syntax tree within each source file then traversing it to couple functions with their associated documentation.

If no documentation exists the function will still be available in the documentation but will display a "This needs documentation" description to the user.

Angular App

The angular app component of the project is a simple web app that can be used to display the JSON documentation generated in the node module. it provides;

• Separate Pages for each project documented
• Source code display
• Tree view code navigation based on function namespace
• Project readme display

Run the generation

below is a simple gulp task that ingests the desired files/directories and then generates documentation JSON

Options

--ftp however you decide to include the call to documental in your build you can pass this CLI flag into the task ( e.g. gulp docs --ftp ) which will initiate an ftp upload as well as building the docs.

Configuration

A configuration file documental.config.json should be placed alongside the gulp file that you use to build your project.

just a couple of configuration items are needed for the module to get going, the minimal configuration object provides the following;

this configuration is required should you decide to use the bundled angular app to display your docs. At the very least an output location should be provided.

The Output

Documental outputs three JSON files each with a specific function that will be useful weather the bundled angular app is used or not;

1. < project-name >-autocomplete.json
2. < project-name >-menuTree.json
3. < project-name >-sourcemap.json

autocomplete.json This JSON file contains pairs of namespaced function names alongside their more common names ( i.e. a search term for comparison and a logical path location )

menuTree.json A menu tree is also generated, levels and nesting are decided by the namespacing of functions.

within the the Angular app a slightly changed version of EasyTree is being used ( fork at my github ) currently to generate the tree view of the source, the format of this tree follows the easytree format.

sourcemap.json The main meat of the operation is located in the sourcemap. This contains the source code of each function as well as other neccacary properties such as its namespace and any associated JSDoc tags.

These files can now be consumed however you choose!

build the gulp module from source

you can now adjust test.gulpfile.js to point to the desired files and run the documentation task. Note; if you want to use the app when building from source, make sure you have built this also. The process is outlined below.

Source Structure

First grab the project dependancies using bower and npm;

The first point of call in extending the basic functionality of documental is from the plugins aplugin takes a SpiderMonkey AST node and returns an object in the following standard ( or false )

these are returned to the parser which will then integrate the data into the menu / sourcemap / autocomplete files. Adding another layer in the parsing is as simple as creating a new source file and extending the documentalCore.plugins object with a function, having the signiture;

examples can be found in the already existing plugins.

build the app code with gulp

The app will be built to the dist/ directory, JSON generated from the node module can be placed in the dist/data directory

build the app code to the gulp module directory ( source )

build the app code to a ftp location, defined in app/ftp.config.json

Adding Documentation

The app/dist/data/ directory is where the app will look for the three JSON files generated by the node module. These files should be placed here ( this location can be placed in the documental.config.json if desired )

Accessing Documentation

The documentation can be accessed through the Angular app using the project name that was given to the documental.config.json file.

for example if running a localhost server from the app/dist directory