On 07/16/2012 11:22 PM, no-re...@cfengine.com wrote: > Forum: CFEngine Help > Subject: Re: Documenting policy > Author: sauer > Link to topic: https://cfengine.com/forum/read.php?3,26480,26487#msg-26487 > > Just as something which might get you thinking (because I don't have code I > can share)... > > I haven't figured out how to get cf-know or cf-report to do anything useful, > so I've just been implementing a standard practice of making the last line in > any promise a comment attribute. Not only does that reduce the frequency > with which I screw up a comma/semicolon when adding or removing attributes, > but it also lends itself to automatic documentation. I've got 2/3 of a > working perl CFEngine policy parser working, and my end goal is to implement > an automatic documentation-generating system. What I'm doing so far is just > listing the promises under their containing bundle in sort of a tree view > with the comments added. Then a few specific significant parts of the policy > - like files whose permissions are managed - which get handled specially. > Report promises are structured using a few consistent formats, so I can > easily pull out the differnet kinds of reports based on which pattern they > match. > > It's work better if I used methods to structure includes, as then I'd just > put comments on the methods as the high-level documentstion, and allow you to > drill down to lower-level documentation. But I had performance issues with > that structre that I didn't like, so I've moved to dynamically building an > array of includes and having one master bundle sequence with very few method > promises. It performs better and I think is easier to manage, but throws a > monkey wrench into my documentation. :) > > For more detail than what can be put into comment fields (which is all of my > documentation right now, as the parser isn't done), I'm using Trac. The > policy is in Subversion, and I use the Trac wiki to document things while > linking in to the policy source for details. It's not auto-updating yet, but > the plan is for the autodoc system to make RPC calls into Trac to update > links and whatnot based on *something* - javadoc-style embedded comments, > cf-know structures, or something like that. I'll cross that bridge when I > come to it. > > _______________________________________________ > Help-cfengine mailing list > Help-cfengine@cfengine.org > https://cfengine.org/mailman/listinfo/help-cfengine >
I am also in the process of documentation of our bundles. I have also installed
trac and want to generate the wiki pages. I have
come up with a simple approach. The team is used tot the wiki syntax. So in
the bundle are documentation snippets, Then we execute
a script that generates the docs and upload it to our TRAC wikijust like 'sauer'
#%{
11 # = certificate.cf =
12 # This bundles will mannage the certificate files on a host:
13 # * It can install a global cacert file with known root authorities.
14 # * It can install a host certificate, used for ldap/apache/...
15 #
16 # This bundle is tested on:
17 # * debian
18 #%}
19
20
21 #%{
22 # == Example ==
23 #
24 # Generate the global cacert file for a host:
25 # {{{
26 # methods:
27 # "cacert_file" usebundle => certificate_config();
28 # }}}
29 #
30 # Manage the host certificate, without argument will use cfengine FQDN
variable (sys.fqhost):
31 # {{{
32 # methods:
33 # "host_certifciate" usebundle => certificate_config_host("");
34 # }}}
35
36 # Manage the host certificate, with argument :
37 # {{{
38 # methods:
39 # "host_certifciate" usebundle => certificate_config_host("host1");
40 # }}}
41 #%}
42
43
44 #%{
45 # == Internal Documentation ==
46 #
47 # common variables:
48 # * string: certifcate.config_dir - directory on the host
49 # * string: certifcate.bundle_dir - directory in the policy
server
50 # * string: certifcate.local_ca_dir - directory on host to include
certificate that must include
51 # * string: certifcate.update_ca_file - host command to generate the
cacert file
52 #
53 #%}
--
********************************************************************
* Bas van der Vlies e-mail: b...@sara.nl *
* SARA - Academic Computing Services Amsterdam, The Netherlands *
********************************************************************
smime.p7s
Description: S/MIME Cryptographic Signature
_______________________________________________ Help-cfengine mailing list Help-cfengine@cfengine.org https://cfengine.org/mailman/listinfo/help-cfengine
