[Labs-l] How to fill doc.wikimedia.org?

Wed Feb 6 21:13:01 UTC 2013

Andrew Bogott <abogott at wikimedia.org> wrote:

>> I followed the little question mark help links in the puppet config
>> interface in labsconsole. It leads to doc.wikimedia.org which might be
>> doyxgen.
>> How am I supposed to fill that documentation? I added longer comments to
>> my puppet "roles" to explain the parameters. They don't show (yet). Will
>> they appear when doxygen is next parsing the files? Or do I have to do
>> more? What? Where?

> Fixed (sort of) by this:  https://gerrit.wikimedia.org/r/#/c/47750/

> The doc headers that you wrote had a blank line between
> header and class definition.  That was, apparently, enough
> for the puppet doc tool to think that the comments were
> unrelated.

> So far I've been treating 'puppet doc' as a black box and
> just accepting whatever weirdness it dishes out.  If things
> like this start to be more of a problem then we can consider
> changing the tool or adding lint checks to make sure that
> puppet classes are documented usefully.

It would be nice if at least all puppet classes showing up
in the labsconsole interface have a docstring.  For example,
the "[?]" next to "base::tcptweaks" in "Add instance" di-
alogs leads to an empty page.  Come to think of it, actually
all puppet classes should have at least a line of explana-
tion.

The HTML seems to be valid XML, and descriptions are tagged
with '<div id="description">', but there's probably a
cleaner solution for this.

Tim