Configuration doc generation with Config::Model
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:
To generate these doc, a command like this one was added to the build process:
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 ]