Blog

DocBox 3.0 Released

Michael Born March 15, 2021

Spread the word

Michael Born

March 15, 2021

Spread the word


Share your thoughts

DocBox

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:

  1. From the CommandBox CLI, with DocBox Commands
  2. 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.

Add Your Comment

Recent Entries

October is here, and that means Hacktoberfest!

October is here, and that means Hacktoberfest!

Hacktoberfest is here!

Ortus Solutions is built upon Open source with our flagship products all open source, this event holds a special place in our hearts and it’s a great space to show developers how we are modernizing the CFML language. We invite everyone to get involved and contribute to CFML Community Projects, with documentation, code, and new this year, non-code contributions. 

Maria Jose Herrera
Maria Jose Herrera
October 04, 2022
Using CommandBox Docker Images to Perform Bytecode Source Conversions

Using CommandBox Docker Images to Perform Bytecode Source Conversions

There are times when code needs to be shipped in a compiled state. It might be for obfuscation or source protection, it might just because it runs faster that way, without the CFML server needing to compile templates at runtime. It's an excellent use case for production Docker images and code deploy pipelines.

Jon Clausen
Jon Clausen
October 03, 2022
cbElasticsearch 2.3.3 Released

cbElasticsearch 2.3.3 Released

We are pleased to announce the release of cbElasticsearch version 2.3.3. cbElasticsearch is the Elasticsearch module for the Coldbox platform, and provides a fluent CFML API for interacting with, searching, and serializing to Elasticsearch servers.

This release adds full compatibility for Elasticsearch v8.x as well as maintaining support for Elasticsearch versions 6 and 7.

Jon Clausen
Jon Clausen
October 03, 2022