Module: Hoe::ManualGen

Includes:
FileUtils, FileUtils::DryRun, FileUtils::Verbose
Defined in:
lib/hoe/manualgen.rb

Overview

Rake tasks for generating a project manual or tutorial.

This was born out of a frustration with other static HTML generation modules and systems. I’ve tried webby, webgen, rote, staticweb, staticmatic, and nanoc, but I didn’t find any of them really suitable (except rote, which was excellent but apparently isn’t maintained and has a fundamental incompatibilty with Rake because of some questionable monkeypatching.)

So, since nothing seemed to scratch my itch, I’m going to scratch it myself.

Author:

Defined Under Namespace

Modules: Logging Classes: ErbFilter, Page, PageCatalog, PageFilter, TextileFilter

Constant Summary collapse

VERSION =

Library version constant

'0.3.0'
REVISION =

Version-control revision constant

%q$Revision: cbd7dd95d043 $
DEFAULT_BASE_DIR =

Configuration defaults

Pathname( 'manual' )
DEFAULT_SOURCE_DIR = 
'src'
DEFAULT_LAYOUTS_DIR = 
'layouts'
DEFAULT_OUTPUT_DIR = 
'output'
DEFAULT_RESOURCE_DIR = 
'resources'
DEFAULT_LIB_DIR = 
'lib'
DEFAULT_METADATA = 
OpenStruct.new
DEFAULT_MANUAL_TEMPLATE_DIR = 
Pathname( Gem.datadir('hoe-manualgen') || 'data/hoe-manualgen' )
RESOURCE_EXTNAMES =

A glob pattern for matching resource files when copying them around

%w[ css erb gif html jpg js otf page png rb svg svgz swf ]
RESOURCE_GLOB_PATTERN = 
"**/*.{%s}" % [ RESOURCE_EXTNAMES.join(',') ]
DEFAULT_MANUAL_SUBDIRS =

The subdirectories to create under the manual dir

[
  DEFAULT_SOURCE_DIR,
  DEFAULT_LAYOUTS_DIR,
  DEFAULT_OUTPUT_DIR,
  DEFAULT_RESOURCE_DIR,
  DEFAULT_LIB_DIR,
]

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#manual_base_dir ⇒ Object

Returns the value of attribute manual_base_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_base_dir
  @manual_base_dir
end

#manual_layouts_dir ⇒ Object

Returns the value of attribute manual_layouts_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_layouts_dir
  @manual_layouts_dir
end

#manual_lib_dir ⇒ Object

Returns the value of attribute manual_lib_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_lib_dir
  @manual_lib_dir
end

#manual_metadata ⇒ Object

Returns the value of attribute manual_metadata.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_metadata
  @manual_metadata
end

#manual_output_dir ⇒ Object

Returns the value of attribute manual_output_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_output_dir
  @manual_output_dir
end

#manual_paths ⇒ Object

Returns the value of attribute manual_paths.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_paths
  @manual_paths
end

#manual_resource_dir ⇒ Object

Returns the value of attribute manual_resource_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_resource_dir
  @manual_resource_dir
end

#manual_source_dir ⇒ Object

Returns the value of attribute manual_source_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_source_dir
  @manual_source_dir
end

#manual_template_dir ⇒ Object

Returns the value of attribute manual_template_dir.



555
556
557
 
# File 'lib/hoe/manualgen.rb', line 555

def manual_template_dir
  @manual_template_dir
end

Instance Method Details

#copy_resource(task) ⇒ Object

Copy method for resources – passed as a block to the various file tasks that copy resources to the output directory.



777
778
779
780
781
782
783
784
785
786
787
 
# File 'lib/hoe/manualgen.rb', line 777

def copy_resource( task )
  source = task.prerequisites[ 1 ]
  target = task.name

  when_writing do
    trace "  #{source} -> #{target}"
    mkpath File.dirname( target ), :verbose => $trace unless
      File.directory?( File.dirname(target) )
    install source, target, :mode => 0644, :verbose => $trace
  end
end

#define_existing_manual_tasks(paths) ⇒ Object

Define tasks for generating output for an existing manual.



668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
 
# File 'lib/hoe/manualgen.rb', line 668

def define_existing_manual_tasks( paths )

  # Read all of the filters, pages, and layouts
  load_filter_libraries( paths[:libdir] )
  trace "Creating the manual page catalog with source at %p, layouts in %p" %
    paths.values_at( :sourcedir, :layoutsdir )
  catalog = PageCatalog.new( paths[:sourcedir], paths[:layoutsdir] )

  # Declare the tasks outside the namespace that point in
  desc "Generate the manual"
  task :manual => "manual:build"

  CLEAN.include( paths[:outputdir].to_s )

  # Namespace all our tasks
  namespace :manual do

    # Set up a file task for each resource, then a conversion task for
    # each page in the sourcedir so pages re-generate if they're modified
    setup_resource_copy_tasks( paths[:resourcedir], paths[:outputdir] )
    manual_pages = setup_page_conversion_tasks( paths[:sourcedir], paths[:outputdir], catalog )

    # The main task
    desc "Build the manual"
    task :build => [ :copy_resources, :copy_apidocs, :generate_pages ]

    task :clean do
      RakeFileUtils.verbose( $verbose ) do
        rm_f manual_pages.to_a
      end
      remove_dir( paths[:outputdir] ) if ( paths[:outputdir] + '.buildtime' ).exist?
    end

    desc "Force a rebuild of the manual"
    task :rebuild => [ :clean, :build ]

    desc "Update the resources templates for the manual to the latest versions"
    task :update do
      ask_for_confirmation( "Update the resources/templates in the manual directory?" ) do
        log "Updating..."
        install_manual_directory( paths[:basedir], paths[:templatedir], false )
      end

    end # task :manual

       end
end

#define_manual_setup_tasks(paths) ⇒ Object

Define tasks for creating a skeleton manual



610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
 
# File 'lib/hoe/manualgen.rb', line 610

def define_manual_setup_tasks( paths )
  templatedir = paths[:templatedir]
  trace "Templatedir is: %s" % [ templatedir ]
  manualdir = paths[:basedir]

  desc "Create a manual for this project from a template"
  task :manual do
    log "No manual directory (#{manualdir}) currently exists."
    ask_for_confirmation( "Create a new manual directory tree from a template?" ) do
      log "Generating manual skeleton"
      install_manual_directory( manualdir, templatedir )
    end

  end # task :manual

end

#define_manualgen_tasks ⇒ Object

Set up the tasks for building the manual



584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
 
# File 'lib/hoe/manualgen.rb', line 584

def define_manualgen_tasks

  # Make Pathnames of the directories relative to the base_dir
  basedir = Pathname( self.manual_base_dir )
  @manual_paths = {
    :templatedir => Pathname( self.manual_template_dir ),
    :basedir     => basedir,
    :sourcedir   => basedir + self.manual_source_dir,
    :layoutsdir  => basedir + self.manual_layouts_dir,
    :resourcedir => basedir + self.manual_resource_dir,
    :libdir      => basedir + self.manual_lib_dir,
    :outputdir   => basedir + self.manual_output_dir,
  }

  if basedir.directory?
    trace "Basedir %s exists, so defining tasks for building the manual" % [ basedir ]
    define_existing_manual_tasks( @manual_paths )
  else
    trace "Basedir %s doesn't exist, so defining tasks for creating a new manual" % [ basedir ]
    define_manual_setup_tasks( @manual_paths )
  end

end

#initialize_manualgen ⇒ Object

Hoe callback – set up defaults



567
568
569
570
571
572
573
574
575
576
577
578
579
580
 
# File 'lib/hoe/manualgen.rb', line 567

def initialize_manualgen
  @manual_template_dir = DEFAULT_MANUAL_TEMPLATE_DIR
  @manual_base_dir     = DEFAULT_BASE_DIR
  @manual_source_dir   = DEFAULT_SOURCE_DIR
  @manual_layouts_dir  = DEFAULT_LAYOUTS_DIR
  @manual_output_dir   = DEFAULT_OUTPUT_DIR
  @manual_resource_dir = DEFAULT_RESOURCE_DIR
  @manual_lib_dir      = DEFAULT_LIB_DIR
  @manual_metadata     = DEFAULT_METADATA
  @manual_paths = {}

  self.extra_dev_deps << ['hoe-manualgen', "~> #{VERSION}"] unless
    self.name == 'hoe-manualgen'
end

#install_manual_directory(manualdir, templatedir, include_srcdir = true) ⇒ Object

Generate (or refresh) a manual directory from the specified templatedir.



629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
 
# File 'lib/hoe/manualgen.rb', line 629

def install_manual_directory( manualdir, templatedir, include_srcdir=true )

  self.manual_paths.each do |key, dir|
    mkpath( dir, :mode => 0755 )
  end

  Pathname.glob( templatedir + RESOURCE_GLOB_PATTERN ).each do |tmplfile|
    if tmplfile.to_s =~ %r{/src/}
      trace "Skipping %s" % [ tmplfile ]
      next unless include_srcdir
    end

    # Render ERB files
    if tmplfile.extname == '.erb'
      rname = tmplfile.basename( '.erb' )
      target = manualdir + tmplfile.dirname.relative_path_from( templatedir ) + rname
      template = ERB.new( tmplfile.read, nil, '<>' )

      target.dirname.mkpath unless target.dirname.directory?
      html = template.result( binding() )
      log "generating #{target}"

      target.open( File::WRONLY|File::CREAT|File::TRUNC, 0644 ) do |fh|
        fh.print( html )
      end

    # Just copy anything else
    else
      target = manualdir + tmplfile.relative_path_from( templatedir )
      mkpath target.dirname,
        :mode => 0755, :noop => $dryrun unless target.dirname.directory?
      install tmplfile, target,
        :mode => 0644, :noop => $dryrun
    end
  end
end

#load_filter_libraries(libdir) ⇒ Object

Load the filter libraries provided in the given libdir



718
719
720
721
722
723
 
# File 'lib/hoe/manualgen.rb', line 718

def load_filter_libraries( libdir )
  Pathname.glob( libdir.expand_path + '*.rb' ) do |filterlib|
    trace "  loading filter library #{filterlib}"
    require( filterlib )
  end
end

#setup_page_conversion_tasks(sourcedir, outputdir, catalog) ⇒ Object

Set up the main HTML-generation task that will convert files in the given sourcedir to HTML in the outputdir



728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
 
# File 'lib/hoe/manualgen.rb', line 728

def setup_page_conversion_tasks( sourcedir, outputdir, catalog )

  # we need to figure out what HTML pages need to be generated so we can set up the
  # dependency that causes the rule to be fired for each one when the task is invoked.
  manual_sources = Rake::FileList[ catalog.path_index.keys.map(&:to_s) ]
  trace "   found %d source files" % [ manual_sources.length ]

  # Map .page files to their equivalent .html output
  html_pathmap = "%%{%s,%s}X.html" % [ sourcedir, outputdir ]
  manual_pages = manual_sources.pathmap( html_pathmap )
  trace "Mapping sources like so: \n  %p -> %p" %
    [ manual_sources.first, manual_pages.first ]

  # Output directory task
  directory( outputdir.to_s )
  file outputdir.to_s do
    touch outputdir + '.buildtime'
  end

  # Rule to generate .html files from .page files
  rule(
    %r{#{outputdir}/.*\.html$} => [
      proc {|name| name.sub(/\.[^.]+$/, '.page').sub(outputdir.to_s, sourcedir.to_s) },
      outputdir.to_s
     ]) do |task|

    source = Pathname.new( task.source )
    target = Pathname.new( task.name )
    log "  #{ source } -> #{ target }"

    page = catalog.path_index[ source ]
    html = page.generate( self.manual_metadata )
    #trace "  page object is: %p" % [ page ]

    target.dirname.mkpath
    target.open( File::WRONLY|File::CREAT|File::TRUNC ) do |io|
      io.write( html )
    end
  end

  # Group all the manual page output files targets into a containing task
  desc "Generate any pages of the manual that have changed"
  task :generate_pages => manual_pages
  return manual_pages
end

#setup_resource_copy_tasks(resourcedir, outputdir) ⇒ Object

Set up a rule for copying files from the resources directory to the output dir.



791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
 
# File 'lib/hoe/manualgen.rb', line 791

def setup_resource_copy_tasks( resourcedir, outputdir )
  glob = resourcedir + RESOURCE_GLOB_PATTERN
  resources = FileList[ glob.to_s ]
  resources.exclude( /\.svn/ )
  target_pathmap = "%%{%s,%s}p" % [ resourcedir, outputdir ]
  targets = resources.pathmap( target_pathmap )
  copier = self.method( :copy_resource ).to_proc

  # Create a file task to copy each file to the output directory
  resources.each_with_index do |resource, i|
    file( targets[i] => [ outputdir.to_s, resource ], &copier )
  end

  desc "Copy API documentation to the manual output directory"
  task :copy_apidocs => [ outputdir.to_s, :docs ] do
    # Since Hoe hard-codes the 'docs' output dir, it's hard-coded
    # here too.
    apidir = outputdir + 'api'
    self.manual_metadata.api_dir = apidir
    cp_r( 'doc', apidir )
  end

  # Now group all the resource file tasks into a containing task
  desc "Copy manual resources to the output directory"
  task :copy_resources => targets do
    log "Copying manual resources"
  end
end