publish HTML documentation of our puppet source
there are ways of generating HTML versions of Puppet source code, based on the docstrings littering the source code. i've done some tentative runs of this and it looks ... interesting. the utility of this is currently limited by the fact that only 35% of the source is documented, according to puppet strings
, but i figured I would document the efforts I've done so far already.
Koumbit uses the following Rakefile to generate the docs for their monorepo:
#require 'bundler/gem_tasks'
task :default do
# nothing
puts('no action')
end
task :doc do
require 'puppet-strings/tasks/generate'
# This doesn't seem to really process node files, but
# an exclude of manifests/ might be interesting.
Rake::Task['strings:generate'].invoke(
# This list of included files was taken from
# https://github.com/puppetlabs/puppet-strings#generating-documentation-with-puppet-strings
# and should correspond to what puppet-strings does by default, but spanned
# over all of the code directories in the control repos.
# It's possible that some directories might include .rb files that were not
# specified.. We'll have to fix this if we ever encounter such an issue.
'**/manifests/**/*.pp **/functions/**/*.pp **/types/**/*.pp **/tasks/**/*.pp **/lib/**/*.rb',
'false',
'false',
'markdown'
)
end
# Generate documentation only for manifests in site/
# This will help to verify if there's anything in our own code that's missing
# comments for documentation. The run will be faster and less noisy than when
# we generate everything.
# Note, though, that it will create an index only for things in site/
task :doc_site do
require 'puppet-strings/tasks/generate'
# This doesn't seem to really process node files, but
# an exclude of manifests/ might be interesting.
Rake::Task['strings:generate'].invoke(
'site/**/*.pp site/**/*.rb',
'false',
'false',
'markdown'
)
end
task :doc_clean do
system("rm -rf doc")
end
task :doc_upload, [:ftp_host, :ftp_port, :ftp_user, :ftp_pass, :ftp_dir] do |t, args|
puts "lftp -e \"mirror -R doc #{args[:ftp_dir]}\" -u #{args[:ftp_user]},#{args[:ftp_pass]} -p #{args[:ftp_port]} #{args[:ftp_host]}"
system("lftp -e \"mirror -R doc #{args[:ftp_dir]}; quit\" -u #{args[:ftp_user]},#{args[:ftp_pass]} -p #{args[:ftp_port]} #{args[:ftp_host]}")
end
Notice the two different jobs for site
(private) and modules
(public).