Faced with Two Problems
- How to visualize the order of Cfengine configuration files
- How to describe the meaning of the Cfengine configuration files
I found it difficult as I was trying to structure the Cfengine architecture remembering what files defined which classes and when. It is common for people to think that when they import a file that all the classes and variables defined will then be available to the in the cfengine file doing the importing. But this isn't true. So it causes you to structure things different. This is where it hlpes to have a good name for the file and what it does internally. An example is a groups file.
Motivations
- Provide documenation for our customers
- Give back to the Cfengine community
First Attempt at Visualization
- Draw by hand a visual representation using inkscape
- Increased my undertstanding of problem
- Use of colors helped categorize types of cfengine files
- Problems
- Lengthy initial development time (took me better part of a day)
- No automatic means to syncronize diagram to code (inefficient)
- Visualization that could be handled by the computer was left to the developer (let the computer think for you)
cd ~/cfenginedoc-wip/ && inkview sysnav_cfengine_order.svg &
Enter GraphViz
- Was introduced to Postgresql Autodoc
- Early experiments by hand yielded compelling results
- Wrote a perl script to automatically generate the graphs
A couple of days later a coworker was demostrating Postgresql Autodoc. Which uses GraphViz to graphically describe the database tables.
Bring on NaturalDocs
- Still needed to solve the problem of how to describe the meaning of Cfengine configuration files
- Also needed:
- to keep the description in sync with the source
- automate the building of reference documentation
- A coworker found NaturalDocs; decided to use it for SysNav User Interface (SUI)
- An intial attempt at using it yielded positive results
Still need to solve the problem of documenting what Cfengine was doing. It is important in my organization to keep the documentation close to the source.
What's left?
- It's obvious, link the two together
- Write some shell scripts to automate the build
- Quick demo ...
TODO
- Make the code publicly available
- Add the ability to add or remove classes when building the graph
- Split up the graphs intelligently into chunks
- Add an index page with links to the chunks and the index page of the NaturalDocs output
- Add a header and footer for all pages
- Define a good convention for using NaturalDocs
- Develop built-in language support for Cfengine into NaturalDocs
- Take suggestions from the community
Resources
- CfengineDoc - http://www.pearcec.com/cfenginedoc/
- GraphViz - http://www.graphviz.org
- NaturalDocs - http://www.naturaldocs.org
- Cfengine - http://www.cfengine.org
- cfwiki.org - http://www.cfwiki.org
- SysNav - http://www.sysnav.com
- Inkscape - http://www.inkscape.org
- Digibadge - http://www.digibadge.com
Christian Pearce <pearcec@perfectorder.com>