From f2aa7d00c50d26d4e86a1ba43039c703d27ef247 Mon Sep 17 00:00:00 2001 From: Peter Huene Date: Sun, 11 Sep 2016 14:46:57 -0700 Subject: [PATCH] (PDOC-63) Implement the Puppet Strings rake tasks. This commit implements the `strings:generate` and `strings:gh_pages:update` rake tasks. The `strings:generate` task is responsible for generating Puppet Strings documentation. The `strings:gh_pages:update` task is responsible for updating the `gh_pages` branch of a GitHub repository with the latest Puppet Strings documentation. --- README.md | 54 +++++++++++++++------------- Rakefile | 4 +++ lib/puppet-strings/tasks.rb | 10 ++++++ lib/puppet-strings/tasks/generate.rb | 23 ++++++++++++ lib/puppet-strings/tasks/gh_pages.rb | 43 ++++++++++++++++++++++ 5 files changed, 110 insertions(+), 24 deletions(-) create mode 100644 lib/puppet-strings/tasks.rb create mode 100644 lib/puppet-strings/tasks/generate.rb create mode 100644 lib/puppet-strings/tasks/gh_pages.rb diff --git a/README.md b/README.md index d087e6b..709fdcf 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ Puppet Strings -============= +============== [![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings) A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser. It is uses YARD and the Puppet Parser to generate HTML documentation about Puppet code and Puppet extensions written in Ruby. It will eventually replace the `puppet doc` command once feature parity has been achieved. - | | | | -------------- |------------------------------------------------------------ | | *Code* | [GitHub][repo] | @@ -193,44 +192,51 @@ Here are a few other good resources for getting started with documentation: * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md) Rake Tasks ------ +---------- -This module is also available as a Gem and makes three rake tasks (`strings:generate`, `strings:serve`, and `strings:gh_pages`) available in `puppet-strings/rake_tasks`. To add this to your module's CI workflow, be sure to add this module to your `Gemfile`: +Puppet Strings comes with two rake tasks: `strings:generate` and `strings:gh_pages:update` available in `puppet-strings/tasks`. -In addition to generating the usual 'doc' directory of HTML documentation, the `strings:generate` rake task will also drop a strings.json file containing a JSON representation of the module into the directory the rake task was run from. +Add the following to your Gemfile to use `puppet-strings`: ```ruby gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git' ``` -To use the rake tasks, `require puppet-strings/rake_tasks` in your `Rakefile`: +In your `Rakefile`, add the following to use the `puppet-strings` tasks: ```ruby -require 'puppet-strings/rake_tasks' +require 'puppet-strings/tasks' ``` -The task `strings:generate` which is provided by including `puppet-strings/rake_tasks` will scan the manifests and lib directory from your single module. If you need to document a complete, or part of a, puppet tree, you can use the `PuppetStrings::RakeTasks::Generate` task. This rake task will by default overwrite strings:generate unless you specify a custom name. See the example below on how you can use it and which options it supports. +The `strings:generate` task can be used to generate documentation: -```ruby -require 'puppet-strings/rake_tasks/generate' - -PuppetStrings::RakeTasks::Generate.new(:documentation) do |task| - task.paths = ['site/roles','site/profiles','modules/internal'] - task.excludes = ['/vendor/','/example/'] - task.options = {} # disables the strings.json output - # module_resourcefiles are the patterns of included files. Below is the default. - # task.module_resourcefiles = ['manifests/**/*.pp', 'lib/**/*.rb'] -end +``` +$ rake strings:generate ``` -The `strings:gh_pages` task will generate your Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will: +The task accepts the following parameters: - 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** +* `patterns`: the search patterns to use for finding files to document (defaults to `manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb`). +* `debug`: enables debug output when set to `true`. +* `backtrace`: enables backtraces for errors when set to `true`. +* `markup`: the markup language to use (defaults to `markdown`). +* `yard_args`: additional arguments to pass to YARD. -This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch. Please keep this in mind as it **will be destructive** if not used properly. +An example of passing arguments to the `strings:generate` Rake task: + +``` +$ rake strings:generate\['**/*.pp **/*.rb, true, true, markdown, --readme README.md'] +``` + +The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will: + +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 `--force` flag** + +This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch. +***Please note this operation will be destructive if not used properly.*** Developing and Contributing ----- diff --git a/Rakefile b/Rakefile index 459dda0..adb0c64 100644 --- a/Rakefile +++ b/Rakefile @@ -1,6 +1,10 @@ require 'rubygems' require 'puppetlabs_spec_helper/rake_tasks' require 'puppet-lint/tasks/puppet-lint' + +# Add our own tasks +require 'puppet-strings/tasks' + PuppetLint.configuration.send('disable_80chars') PuppetLint.configuration.ignore_paths = ["spec/**/*.pp", "pkg/**/*.pp"] diff --git a/lib/puppet-strings/tasks.rb b/lib/puppet-strings/tasks.rb new file mode 100644 index 0000000..255ff60 --- /dev/null +++ b/lib/puppet-strings/tasks.rb @@ -0,0 +1,10 @@ +require 'rake' +require 'rake/tasklib' + +module PuppetStrings + # The module for Puppet Strings rake tasks. + module Tasks + require 'puppet-strings/tasks/generate.rb' + require 'puppet-strings/tasks/gh_pages.rb' + end +end diff --git a/lib/puppet-strings/tasks/generate.rb b/lib/puppet-strings/tasks/generate.rb new file mode 100644 index 0000000..616deda --- /dev/null +++ b/lib/puppet-strings/tasks/generate.rb @@ -0,0 +1,23 @@ +require 'puppet-strings' + +# Implements the strings:generate task. +namespace :strings do + desc 'Generate Puppet documentation with YARD.' + task :generate, :patterns, :debug, :backtrace, :markup, :json, :yard_args do |t, args| + patterns = args[:patterns] + patterns = patterns.split if patterns + patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS + + options = { + debug: args[:debug] == 'true', + backtrace: args[:backtrace] == 'true', + markup: args[:markup] || 'markdown', + } + + options[:json] = args[:json] if args.key? :json + options[:yard_args] = args[:yard_args].split if args.key? :yard_args + + PuppetStrings.generate(patterns, options) + end +end + diff --git a/lib/puppet-strings/tasks/gh_pages.rb b/lib/puppet-strings/tasks/gh_pages.rb new file mode 100644 index 0000000..c6b5262 --- /dev/null +++ b/lib/puppet-strings/tasks/gh_pages.rb @@ -0,0 +1,43 @@ +require 'puppet-strings/tasks' + +namespace :strings do + namespace :gh_pages do + desc 'Checkout the gh-pages branch for doc generation.' + task :checkout do + if Dir.exist?('doc') + fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git') + Dir.chdir('doc') do + system 'git checkout gh-pages' + system 'git pull --rebase origin gh-pages' + end + else + git_uri = `git config --get remote.origin.url`.strip + fail "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $?.success? + + Dir.mkdir('doc') + Dir.chdir('doc') do + system 'git init' + system "git remote add origin #{git_uri}" + system 'git pull origin gh-pages' + system 'git checkout -b gh-pages' + end + end + end + + desc 'Push new docs to GitHub.' + task :push do + Dir.chdir('doc') do + system 'git add .' + system "git commit -m '[strings] Generated Documentation Update'" + system 'git push origin gh-pages -f' + end + end + + desc 'Run checkout, generate, and push tasks.' + task :update => [ + :checkout, + :'strings:generate', + :push, + ] + end +end