Hi all,
I''ve been thinking about this for a while, and I think I''ve
finally
come up with the "right" way to do this.
There''s a lot of data in Puppet that''d be useful as
documentation but
is not currently exposed all that well, especially on the command-
line. Just a few examples:
- Which providers for which types are functional on the current machine
- Whether a given parameter is valid for a given provider
- What transaction reports exist
- What functions exist
I''ve written ''puppetdoc'' to turn some of this
information into
monolothic documents, but it''s difficult to add new reference
documents to `puppetdoc`, and it has a lot of text stored in-line.
I''m thinking that I''ll create a new type of autoloading file,
''reference'', and I''ll move everything in `puppetdoc`
to be instances
of that, then add the other references I want and enhance puppetdoc
to just load those.
I''m going to start on this immediately, because this will make it
very easy to make internals visible, and I''ll be able to add new
reference types very easily.
It''s also a goal of mine to make puppetdoc able to produce man-style
pages, which is easy with docutils (all Puppet docs are written in
Restructured Text, for which there''s only a parser in Python''s
docutils).
(Added as https://reductivelabs.com/trac/puppet/wiki/
ReferenceDocumentation)
Comments?
--
If you can''t be a good example, then you''ll just have to be
a horrible
warning. -- Catherine Aird
---------------------------------------------------------------------
Luke Kanies | http://reductivelabs.com | http://madstop.com
