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/