automatically generate puppet-strings for modules & publish as gh-pages

[igalic]

We should automatically generate a module's documentation from puppet-strings and publish it to gh-pages.
As a fall-back, we can just convert the readme to index.html

This way, all modules will be accessible under https://puppet.community/puppet-{{name}}

[3flex]

This should be straightforward now with puppet-strings' strings:gh_pages:update rake task which does exactly that - it will (from the strings README):

1. Create a doc directory in the root of your project
2. Check out the gh-pages branch of the current repository in the doc directory (it will create a branch if one does not already exist)
3. Generate strings documentation using the strings:generate task
4. Commit the changes and push them to the gh-pages branch with the -f flag

Possible plan:

• Update modulesync_config with a config option (set false by default) to automatically build docs on release (I'm guessing some modules won't be compatible with puppet-strings. Or should it be built for all anyway, since something is better than nothing?)
• Update voxpupuli-release-gem to call strings:gh_pages:update as part of the release process

This should be safe to run on all modules since the task in puppet-strings checks fails if the /doc directory exists and is not a git repository. This will prevent any modules that might have an existing /doc directory from being clobbered.

Once this is in place it might be good to add an enhancement to automatically publish a list of modules on voxpupuli.org which links directly to the documentation based on https://raw.githubusercontent.com/voxpupuli/modulesync_config/master/managed_modules.yml

[3flex]

Currently puppet strings doesn't exit with non-zero exit code when there's a failure, raised https://tickets.puppetlabs.com/browse/PDOC-89 to have this looked at. I don't think the above plan will work without it, unless doc build failures are considered acceptable before tagging a release?

My thoughts were that this would be done as a final step prior to the push to the Forge, and fail if the docs can't be built.

Another option is checking that docs can be built as part of regular Travis builds (without pushing to gh-pages) so any failures are found before attempting to build for the release.

[igalic]

imo, documentation is an integral part of a release, so they should be… correct.

[ekohl]

We regenerate the REFERENCE.md on release, if it's present: https://github.com/voxpupuli/voxpupuli-release/blob/52377db498ec9418fa0100d47bd2226ca22cd60b/lib/voxpupuli/release/rake_tasks.rb#L105

Then there's also a CI check to update REFERENCE.md if it's outdated: https://github.com/puppetlabs/puppetlabs_spec_helper/blob/ebb0ab0e4243b234b21f6b43669164b919c49f95/lib/puppetlabs_spec_helper/rake_tasks.rb#L213-L219

This all relies on REFERENCE.md being present.

We don't publish to GH pages, but we host https://www.puppetmodule.info now (after it was transferred from Dominic).

For now I'd suggest this to close this.

[bastelfreak]

I also agree that we should close this. We publish the docs now at https://www.puppetmodule.info/