Say hello to DocBox 3.0! This new version adds JSON output format, multiple strategy support, and a raft of improvements across the board. Check it out by running box install docbox@3 to install the new version.
What Is DocBox?
DocBox is a CFML library that converts CFML component metadata and comment blocks into documentation. You can choose from three documentation formats - HTML, JSON, or an XMI file for generating UML diagrams - and generate docs from the CommandBox CLI or from your application.
In other words, DocBox takes you from code comments to delicious documentation in a matter of minutes.
Why Is DocBox?
DocBox exists to fill the gap between hand-written documentation (such as coldbox.ortusbooks.com ) and no documentation whatsoever. DocBox is especially handy for public libraries, as it makes it simple for consumers to see the available classes and method signatures without needing to manually read or search the source code.
Installing DocBox
There are two main ways to generate app documentation using DocBox:
- From the CommandBox CLI, with DocBox Commands
- From your CFML app, with the DocBox library
From CommandBox
To use DocBox within CommandBox, you'll want to run install commandbox-docbox and follow that with docbox help to see the available commands and syntax.
Just as an example, here's a typical command to generate documentation for a Coldbox application:
docbox generate source=./ mapping=app excludes=tests|coldbox|testbox|modules strategy-outputDir=./tmp strategy-projectTitle=""
For more examples and documentation, check out the DocBox Commands project on Forgebox.
From Your CFML App
For generating documentation from your CFML application, run install docbox within Commandbox to install the docbox library.
Now you can create a CFML file to instantiate the Docbox class, configure a few settings, and run the documentation generator:
new docbox.DocBox( "HTML", {
projectTitle : "CommandBox",
outputDir : expandPath( './docs' )
} )
.generate(
source = expandPath( "/app" ),
mapping = "app",
excludes="(coldbox)"
);
Check out the Docbox documentation for configuration help.
CFCasts Series
Are you interested in using DocBox for your projects? We are working on a "Using DocBox" CFCasts series for those devs who need a bit more help getting started. If you like the idea of automated documentation but don't know where to start, you'll love this new series on CFCasts. Using DocBox will be available in the coming weeks.
Release Notes
3.0.0
Added
- New
json output strategy for machine-readable documentation.
- New
addStrategy() method for generating multiple documentation formats simultaneously.
- New documentation site hosted at docbox.ortusbooks.com
- New TestBox suite of tests ensuring CF2018, CF2016 and Lucee compatibility on every output strategy.
Changed
- Can configure strategy with "alias" name, like
strategy="HTML".
Removed
- Removed HTML as the default strategy. You will need to explicitly pass this to the constructor or to
docbox.addStrategy( "HTML", props ) to set your desired output format.
Luis Majano
Jon Clausen
Michael Born
Paulina Lainez
Eric Peterson
Brad Wood