Skip to content

Configuration doc generation with Config::Model

April 8, 2011

Hello

When a project comes with configuration files, project developers have to write configuration doc. Be it as man pages or as comments in configuration files.

This is a boring, but necessary task to provide documentation to users.

There’s a way to get more with a similar effort. By writing this doc as models (i.e. in a format usable by Config::Model), you will get:
– generated man pages
– configuration GUIs
– configuration command line

And with a little extra effort, you will also get:
– immediate validation data entered by user
– configuration upgrade tools

But let’s focus on generating documentation.

A configuration model is more or less a list of configuration parameters with their constraints and description. In previous versions of Config::Model, the parameter description was used to generate online help in the GUI.

Parameter description is now also used to generate configuration documentation. The constraints which are used to validate user input, are also used to provide more details to the documentation of the parameters.

The help text in the model that will be used to generate doc can be plain text or contain pod markups to enhance the look of the doc (be it generated or displayed in the GUI).

Here are some links to some example of models and the corresponding generated documents:

Dpkg::Source model generated doc
Dpkg::Copyright model generated doc
Sshd model generated doc

To generate these doc, a command like this one was added to the build process:

cme gen-class-pod

The generated pod files can then be converted to man pages, plain text, html depending on your needs.

Feel free to send a mail on config-model users list (config-model-users at lists.sourceforge.net) if you need help.

All the best

[ Note: edited to update links and commands ]

Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: