Opened 2 months ago

#31633 new enhancement

publish HTML documentation of our puppet source

Reported by: anarcat Owned by: tpa
Priority: Low Milestone:
Component: Internal Services/Tor Sysadmin Team Version:
Severity: Normal Keywords:
Cc: Actual Points:
Parent ID: #29387 Points:
Reviewer: Sponsor:

Description

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).

Child Tickets

Change History (0)

Note: See TracTickets for help on using tickets.