From ccba436af54ff690c3853bf015e43767a356a7d6 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 08:01:35 +0100 Subject: readme_generator: script to generate README.md files for github to use. --- readme_generator.pl | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 readme_generator.pl (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl new file mode 100644 index 0000000..20e7312 --- /dev/null +++ b/readme_generator.pl @@ -0,0 +1,61 @@ +#!/usr/bin/env perl + +use strict; +use warnings; + +# Goal: extract the comments from the top of each script file, and +# turn them into some sort of markdown-style README.md for github to nom on. +# +# Not sure how it's going to work with multiple files in a dir though. Sections? + + +use File::Find; +use File::Spec; +use Pod::Markdown; + +my @dirs = @ARGV // '.'; + +find(\&wanted, @dirs); + +sub wanted { + my ($file, $dir, $path) = ($_, $File::Find::dir, $File::Find::name); + return unless $file =~ m/\.pl$/; + + _err("processing file: $path"); +} + +sub read_input_file { + my ($path, $filename) = @_; + + my $filepath = File::Spec->catfile($path, $filename); + + open my $rfh, '<', $filepath or die "Couldn't open $filepath for output: $!"; + + _err("reading $filepath"); + + my $parser = Pod::Markdown->new; + + $parser->parse($rfh); + + close $rfh; + + create_output_file($path, 'README.md', $parser); +} + +sub create_output_file { + my ($path, $filename, $parser) = @_; + + my $filepath = File::Spec->catfile($path, $filename); + + _err("Writing to $filepath"); + + open my $wfh, '>', $filepath or die "Couldn't open $filepath for output: $!"; + print $wfh $parser->as_markdown; + close $wfh; +} + +sub _err { + my ($msg, @args) = @_; + my $str = sprintf($msg, @args); + print STDERR $str; +} -- cgit v1.2.3 From 9d391a4fc542b559e28cb3b343a9e725a87691e5 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 08:11:37 +0100 Subject: readme_generator: made it actually work. --- readme_generator.pl | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index 20e7312..5a997e4 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -12,8 +12,11 @@ use warnings; use File::Find; use File::Spec; use Pod::Markdown; +use feature qw/say/; +use Cwd; +my @dirs = map { File::Spec->catdir(getcwd(), $_) } @ARGV; -my @dirs = @ARGV // '.'; +die unless @dirs; find(\&wanted, @dirs); @@ -22,30 +25,31 @@ sub wanted { return unless $file =~ m/\.pl$/; _err("processing file: $path"); + read_input_file($dir, $file); } sub read_input_file { - my ($path, $filename) = @_; + my ($dir, $filename) = @_; - my $filepath = File::Spec->catfile($path, $filename); + my $filepath = File::Spec->catfile($dir, $filename); - open my $rfh, '<', $filepath or die "Couldn't open $filepath for output: $!"; + open my $rfh, '<', $filepath or die "Couldn't open $filepath for input: $!"; _err("reading $filepath"); my $parser = Pod::Markdown->new; - $parser->parse($rfh); + $parser->parse_from_filehandle($rfh); close $rfh; - create_output_file($path, 'README.md', $parser); + create_output_file($dir, 'README.md', $parser); } sub create_output_file { - my ($path, $filename, $parser) = @_; + my ($dir, $filename, $parser) = @_; - my $filepath = File::Spec->catfile($path, $filename); + my $filepath = File::Spec->catfile($dir, $filename); _err("Writing to $filepath"); @@ -57,5 +61,5 @@ sub create_output_file { sub _err { my ($msg, @args) = @_; my $str = sprintf($msg, @args); - print STDERR $str; + say STDERR $str; } -- cgit v1.2.3 From b659b7ec8d3875f714af977cdf92844a9e303e21 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 08:36:21 +0100 Subject: readme: fixed generator to not stomp if multiple files in one dir. Doesn't auto-display though. Maybe need to generate an index? (But where to store it?) --- readme_generator.pl | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index 5a997e4..dc3b277 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -43,7 +43,14 @@ sub read_input_file { close $rfh; - create_output_file($dir, 'README.md', $parser); + my @other_files = glob($dir . "/*.pl"); + + if (@other_files > 1) { + $filename =~ s/\.pl$//; + create_output_file($dir, "README-$filename.md", $parser); + } else { + create_output_file($dir, "README.md", $parser); + } } sub create_output_file { -- cgit v1.2.3 From 04e9b16d8f414d60bb53a270c38ed1ac8a1b6629 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 09:43:58 +0100 Subject: fixed readme_generator again to append to files, rather than trying to create different ones for each script in a dir. Needs a way to force it to completely regen though, otherwise it'll just keep appending each tiem. --- readme_generator.pl | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index dc3b277..67da7ac 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -45,12 +45,12 @@ sub read_input_file { my @other_files = glob($dir . "/*.pl"); - if (@other_files > 1) { - $filename =~ s/\.pl$//; - create_output_file($dir, "README-$filename.md", $parser); - } else { + # if (@other_files > 1) { + # $filename =~ s/\.pl$//; + # create_output_file($dir, "README-$filename.md", $parser); + # } else { create_output_file($dir, "README.md", $parser); - } + # } } sub create_output_file { @@ -58,9 +58,20 @@ sub create_output_file { my $filepath = File::Spec->catfile($dir, $filename); + my $markdown = $parser->as_markdown; + return unless length chomp($markdown); + return if $markdown =~ m/^\s*$/; + _err("Writing to $filepath"); - open my $wfh, '>', $filepath or die "Couldn't open $filepath for output: $!"; + my $sec_sep = ''; + if (-f $filepath) { + _err("$filepath already exists, going to append"); + $sec_sep = "\n\n* * * *\n\n"; + } + + open my $wfh, '>>', $filepath or die "Couldn't open $filepath for output: $!"; + print $wfh $sec_sep; print $wfh $parser->as_markdown; close $wfh; } -- cgit v1.2.3 From 8f2c0f48264fd91477c0d2b049b964d9088bbb6c Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 10:27:56 +0100 Subject: vim-mode/vim_mode: more changes to docs and generator. Starting to look almost readable now. --- readme_generator.pl | 43 +++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index 67da7ac..2062ad1 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -14,6 +14,15 @@ use File::Spec; use Pod::Markdown; use feature qw/say/; use Cwd; + +my $overwrite = $ARGV[0]; +if ($overwrite =~ m/--overwrite/) { + shift @ARGV; # remove it form list of dirs. + $overwrite = 1; +} else { + $overwrite = 0; +} + my @dirs = map { File::Spec->catdir(getcwd(), $_) } @ARGV; die unless @dirs; @@ -32,25 +41,12 @@ sub read_input_file { my ($dir, $filename) = @_; my $filepath = File::Spec->catfile($dir, $filename); - - open my $rfh, '<', $filepath or die "Couldn't open $filepath for input: $!"; - _err("reading $filepath"); my $parser = Pod::Markdown->new; + $parser->parse_from_file($filepath); - $parser->parse_from_filehandle($rfh); - - close $rfh; - - my @other_files = glob($dir . "/*.pl"); - - # if (@other_files > 1) { - # $filename =~ s/\.pl$//; - # create_output_file($dir, "README-$filename.md", $parser); - # } else { - create_output_file($dir, "README.md", $parser); - # } + create_output_file($dir, "README.md", $parser); } sub create_output_file { @@ -59,20 +55,27 @@ sub create_output_file { my $filepath = File::Spec->catfile($dir, $filename); my $markdown = $parser->as_markdown; + return unless length chomp($markdown); return if $markdown =~ m/^\s*$/; - _err("Writing to $filepath"); my $sec_sep = ''; - if (-f $filepath) { - _err("$filepath already exists, going to append"); + + if (-f $filepath and not $overwrite) { + _err("$filepath already exists, going to append") unless $overwrite; $sec_sep = "\n\n* * * *\n\n"; } - open my $wfh, '>>', $filepath or die "Couldn't open $filepath for output: $!"; + my $mode = $overwrite ? '>' : '>>'; + + _err("Writing to $mode $filepath"); + + open my $wfh, $mode, $filepath + or die "Couldn't open $filepath for $mode output: $!"; + print $wfh $sec_sep; - print $wfh $parser->as_markdown; + print $wfh $parser->as_markdown; # fetch it again since we chomped $markdown. close $wfh; } -- cgit v1.2.3 From 25af30751d22508bd7b89fbe2dc367ef8c657af1 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 15:24:48 +0100 Subject: protecting my newly podded docs against a rogue README generator. --- readme_generator.pl | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index 2062ad1..5052afb 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -8,10 +8,12 @@ use warnings; # # Not sure how it's going to work with multiple files in a dir though. Sections? +# Change of plan! Github supports POD, so we just use Pod::Select to scrape it. use File::Find; use File::Spec; -use Pod::Markdown; +use Pod::Select; + use feature qw/say/; use Cwd; @@ -32,9 +34,11 @@ find(\&wanted, @dirs); sub wanted { my ($file, $dir, $path) = ($_, $File::Find::dir, $File::Find::name); return unless $file =~ m/\.pl$/; + return if $file =~ m/^\./; _err("processing file: $path"); - read_input_file($dir, $file); + #read_input_file($dir, $file); + create_output_file($dir, $file); } sub read_input_file { @@ -43,39 +47,34 @@ sub read_input_file { my $filepath = File::Spec->catfile($dir, $filename); _err("reading $filepath"); - my $parser = Pod::Markdown->new; - $parser->parse_from_file($filepath); - create_output_file($dir, "README.md", $parser); } sub create_output_file { - my ($dir, $filename, $parser) = @_; - - my $filepath = File::Spec->catfile($dir, $filename); - - my $markdown = $parser->as_markdown; + my ($dir, $in_file) = @_; - return unless length chomp($markdown); - return if $markdown =~ m/^\s*$/; + my $parser = Pod::Select->new; + my $out_file = "README.pod"; + my $in_file_path = File::Spec->catfile($dir, $in_file); + my $out_file_path = File::Spec->catfile($dir, $out_file); my $sec_sep = ''; - if (-f $filepath and not $overwrite) { - _err("$filepath already exists, going to append") unless $overwrite; - $sec_sep = "\n\n* * * *\n\n"; + if (-f $out_file_path and not $overwrite) { + _err("$out_file_path already exists, going to append") unless $overwrite; + $sec_sep = "\n\n=for html
\n\n"; } my $mode = $overwrite ? '>' : '>>'; _err("Writing to $mode $filepath"); - open my $wfh, $mode, $filepath - or die "Couldn't open $filepath for $mode output: $!"; + open my $wfh, $mode, $out_file_path + or die "Couldn't open $out_file_path for $mode output: $!"; + + $parser->parse_from_file($in_file_path, $wfh); - print $wfh $sec_sep; - print $wfh $parser->as_markdown; # fetch it again since we chomped $markdown. close $wfh; } -- cgit v1.2.3 From 64045f7eb1c3d6ebd8d917891dc7032aa525b038 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 15:29:22 +0100 Subject: readme_generator: now producing POD output. --- readme_generator.pl | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl index 5052afb..e93239e 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -37,19 +37,9 @@ sub wanted { return if $file =~ m/^\./; _err("processing file: $path"); - #read_input_file($dir, $file); create_output_file($dir, $file); } -sub read_input_file { - my ($dir, $filename) = @_; - - my $filepath = File::Spec->catfile($dir, $filename); - _err("reading $filepath"); - - create_output_file($dir, "README.md", $parser); -} - sub create_output_file { my ($dir, $in_file) = @_; @@ -68,13 +58,15 @@ sub create_output_file { my $mode = $overwrite ? '>' : '>>'; - _err("Writing to $mode $filepath"); + _err("Writing to $mode $out_file_path"); open my $wfh, $mode, $out_file_path or die "Couldn't open $out_file_path for $mode output: $!"; $parser->parse_from_file($in_file_path, $wfh); + print $wfh "\n\n=cut\n\n"; + close $wfh; } -- cgit v1.2.3 From 9676393d054a2a1c9b047b166204f229f51cd8a4 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Fri, 22 Apr 2011 03:12:49 +0100 Subject: vim-mode/vim_mode: FINAL doc update for now. Or Else. --- readme_generator.pl | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 readme_generator.pl (limited to 'readme_generator.pl') diff --git a/readme_generator.pl b/readme_generator.pl old mode 100644 new mode 100755 -- cgit v1.2.3