[tor-bugs] #31633 [Internal Services/Tor Sysadmin Team]: publish HTML documentation of our puppet source

[Tor Bug Tracker & Wiki]

#31633: publish HTML documentation of our puppet source
-----------------------------------------------------+--------------------
     Reporter:  anarcat                              |      Owner:  tpa
         Type:  enhancement                          |     Status:  new
     Priority:  Low                                  |  Milestone:
    Component:  Internal Services/Tor Sysadmin Team  |    Version:
     Severity:  Normal                               |   Keywords:
Actual Points:                                       |  Parent ID:  #29387
       Points:                                       |   Reviewer:
      Sponsor:                                       |
-----------------------------------------------------+--------------------
 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).

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/31633>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online