Hashar did some magic and replaced our use of `puppet doc` with yard which is now generating prettier and more useful documentation of the roles and other Puppet components in the MediaWiki-Vagrant project. Go check them out if you are interested: https://doc.wikimedia.org/mediawiki-vagrant/. Try searching for "role::" to get the list of all roles.
Bryan
Nice! I like that by expanding the 'source' option I can see dependencies as well as what it's actually doing in terms of config etc. The textual descriptions of the roles are mostly pretty vague so far; should we expand them for instance to describe what will be installed and how to go about tweaking if tweaking is needed, or just leave that to the source view?
-- brion
On Tue, Jan 10, 2017 at 1:57 PM, Bryan Davis bd808@wikimedia.org wrote:
Hashar did some magic and replaced our use of `puppet doc` with yard which is now generating prettier and more useful documentation of the roles and other Puppet components in the MediaWiki-Vagrant project. Go check them out if you are interested: https://doc.wikimedia.org/mediawiki-vagrant/. Try searching for "role::" to get the list of all roles.
Bryan
Bryan Davis Wikimedia Foundation bd808@wikimedia.org [[m:User:BDavis_(WMF)]] Sr Software Engineer Boise, ID USA irc: bd808 v:415.839.6885 x6855
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Tue, Jan 10, 2017 at 3:12 PM, Brion Vibber bvibber@wikimedia.org wrote:
Nice! I like that by expanding the 'source' option I can see dependencies as well as what it's actually doing in terms of config etc. The textual descriptions of the roles are mostly pretty vague so far; should we expand them for instance to describe what will be installed and how to go about tweaking if tweaking is needed, or just leave that to the source view?
It would be the guy who wrote Bug:1 to send this. :) Documentation levels certainly vary. It would be nice to work on making them a bit better. Patches welcome.
Bryan
On 10/01/17 22:57, Bryan Davis wrote:
Hashar did some magic and replaced our use of `puppet doc` with yard which is now generating prettier and more useful documentation of the roles and other Puppet components in the MediaWiki-Vagrant project. Go check them out if you are interested: https://doc.wikimedia.org/mediawiki-vagrant/. Try searching for "role::" to get the list of all roles.
Hello,
I did that for the operations/puppet.git repository which has doc published on: https://doc.wikimedia.org/puppet/
One can reproduce the documentation build locally by using ruby bundler and invoking the rake task 'doc':
bundle install bundle exec rake doc *browse doc/index.html*
Under the hood it uses [puppet-strings] and the awesome ruby documentation tool [yard]. Note that puppet-strings has a few oddities but overall it is a vast improvement compared to "puppet rdoc".
The format markup for now is 'rdoc', yard supports 'markdown' which might be more convenient, but it should process files ending with '.md' as MarkDown such as the README.md.
For the record the chat with Bryan was roughly:
<antoine> I got doc for operations puppet! <antoine> bryan: would be nice to have the same for MWVagrant <bryan> antoine: patch welcome!
Thank you Bryan for the challenge :-]
[puppet-strings] https://github.com/puppetlabs/puppet-strings [yard] http://yardoc.org/
Le 10/01/2017 à 22:57, Bryan Davis a écrit :
Hashar did some magic and replaced our use of `puppet doc` with yard which is now generating prettier and more useful documentation of the roles and other Puppet components in the MediaWiki-Vagrant project. Go check them out if you are interested: https://doc.wikimedia.org/mediawiki-vagrant/. Try searching for "role::" to get the list of all roles.
Hello,
The Puppet documentation was being overridden by plain ruby documentation so the doc was not quite the one expected.
I fixed it today and it is all fine now. You might have to force refresh your browser to see the puppet classes.
cheers,
wikitech-l@lists.wikimedia.org