From aadf024095e2c7b38d344a42c999262e07079f6b Mon Sep 17 00:00:00 2001 From: Jaimos Skriletz Date: Tue, 5 Nov 2024 23:03:31 -0700 Subject: [PATCH 1/3] Split up macros on PODViewer index page. This splits up the macros on the PODViwer index page to be grouped by their location in the `pg/macros` directory. In addition macros are listed before the libraries. The two macros not in a subdirectory, `PG.pl` and `PGcourse.pl`, are grouped with the pod in `pg/doc`. This makes finding the POD for a specific macro easier. Also update `generate-ww-pg-pd.pl` to match the changes for the POD included on the webwork wiki. --- bin/dev_scripts/PODtoHTML.pm | 22 ++++++- bin/dev_scripts/generate-ww-pg-pod.pl | 25 +++++++- .../pod-templates/category-index.mt | 33 ++++++++++- lib/WeBWorK/ContentGenerator/PODViewer.pm | 34 +++++++++-- templates/ContentGenerator/PODViewer.html.ep | 58 +++++++++++++++---- 5 files changed, 149 insertions(+), 23 deletions(-) diff --git a/bin/dev_scripts/PODtoHTML.pm b/bin/dev_scripts/PODtoHTML.pm index 1956dedfa0..f71a22a5bc 100644 --- a/bin/dev_scripts/PODtoHTML.pm +++ b/bin/dev_scripts/PODtoHTML.pm @@ -43,15 +43,21 @@ sub new { my $class = ref $invocant || $invocant; my @section_list = ref($o{sections}) eq 'ARRAY' ? @{ $o{sections} } : @sections; + my @macros_list = ref($o{macros}) eq 'ARRAY' ? @{ $o{macros} } : (); my $section_hash = {@section_list}; + my $macros_hash = {@macros_list}; my $section_order = [ map { $section_list[ 2 * $_ ] } 0 .. $#section_list / 2 ]; + my $macros_order = @macros_list ? [ map { $macros_list[ 2 * $_ ] } 0 .. $#macros_list / 2 ] : []; delete $o{sections}; + delete $o{macros}; my $self = { %o, idx => {}, section_hash => $section_hash, section_order => $section_order, + macros_hash => $macros_hash, + macros_order => $macros_order, }; return bless $self, $class; } @@ -131,7 +137,19 @@ sub update_index { $subdir =~ s|/.*$||; my $idx = $self->{idx}; my $sections = $self->{section_hash}; - if (exists $sections->{$subdir}) { + if ($subdir eq 'macros') { + $idx->{macros} = []; + if ($pod_name =~ m!^(.+)/(.+)$!) { + my $macros = $self->{macros_hash}; + if ($macros->{$1}) { + push @{ $idx->{$1} }, [ $html_rel_path, $2 ]; + } else { + warn "no macro for '$pod_name'\n"; + } + } else { + push @{ $idx->{doc} }, [ $html_rel_path, $pod_name ]; + } + } elsif (exists $sections->{$subdir}) { push @{ $idx->{$subdir} }, [ $html_rel_path, $pod_name ]; } else { warn "no section for subdir '$subdir'\n"; @@ -152,6 +170,8 @@ sub write_index { pod_index => $self->{idx}, sections => $self->{section_hash}, section_order => $self->{section_order}, + macros => $self->{macros_hash}, + macros_order => $self->{macros_order}, date => strftime('%a %b %e %H:%M:%S %Z %Y', localtime) } ); diff --git a/bin/dev_scripts/generate-ww-pg-pod.pl b/bin/dev_scripts/generate-ww-pg-pod.pl index 9024801fb5..b5a1074d45 100755 --- a/bin/dev_scripts/generate-ww-pg-pod.pl +++ b/bin/dev_scripts/generate-ww-pg-pod.pl @@ -96,18 +96,39 @@ sub process_dir { my $source_dir = shift; return unless $source_dir =~ /\/webwork2$/ || $source_dir =~ /\/pg$/; + my $is_pg = $source_dir =~ /\/pg$/; my $dest_dir = $source_dir; - $dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ if ($source_dir =~ /\/webwork2$/); - $dest_dir =~ s/^$pg_root/$output_dir\/pg/ if ($source_dir =~ /\/pg$/); + $dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ unless $is_pg; + $dest_dir =~ s/^$pg_root/$output_dir\/pg/ if $is_pg; remove_tree($dest_dir); make_path($dest_dir); + my $sections = + $is_pg + ? [ doc => 'Documentation', macros => 'Macros', lib => 'Libraries' ] + : [ bin => 'Scripts', doc => 'Documentation', lib => 'Libraries' ]; + my $macros = $is_pg + ? [ + core => 'Core', + contexts => 'Contexts', + parsers => 'Parsers', + answers => 'Answers', + graph => 'Graph', + math => 'Math', + ui => 'User Interface', + misc => 'Miscellaneous', + deprecated => 'Deprecated' + ] + : []; + my $htmldocs = PODtoHTML->new( source_root => $source_dir, dest_root => $dest_dir, template_dir => "$webwork_root/bin/dev_scripts/pod-templates", dest_url => $base_url, + sections => $sections, + macros => $macros, verbose => $verbose ); $htmldocs->convert_pods; diff --git a/bin/dev_scripts/pod-templates/category-index.mt b/bin/dev_scripts/pod-templates/category-index.mt index 78c9bb3724..96895c9117 100644 --- a/bin/dev_scripts/pod-templates/category-index.mt +++ b/bin/dev_scripts/pod-templates/category-index.mt @@ -23,18 +23,45 @@ % - % my ($index, $content) = ('', ''); + % my ($index, $macro_index, $content, $macro_content) = ('', '', '', ''); + % for my $macro (@$macros_order) { + % next unless defined $pod_index->{$macro}; + % my $new_index = begin + <%= $macros->{$macro} %> + % end + % $macro_index .= $new_index->(); + % my $new_content = begin +

<%= $macros->{$macro} %>

+
+ % for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$macro} }) { + <%= $file->[1] %> + % } +
+ % end + % $macro_content .= $new_content->(); + % } % for my $section (@$section_order) { % next unless defined $pod_index->{$section}; % my $new_index = begin <%= $sections->{$section} %> + % if ($section eq 'macros') { +
+ <%= $macro_index %> +
+ % } % end % $index .= $new_index->(); % my $new_content = begin

<%= $sections->{$section} %>

- % for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) { - <%= $file->[1] %> + % if ($section eq 'macros') { + <%= $macro_content =%> + % } else { + % for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) { + + <%= $file->[1] %> + + % } % }
% end diff --git a/lib/WeBWorK/ContentGenerator/PODViewer.pm b/lib/WeBWorK/ContentGenerator/PODViewer.pm index e07ac0a61a..3d88598315 100644 --- a/lib/WeBWorK/ContentGenerator/PODViewer.pm +++ b/lib/WeBWorK/ContentGenerator/PODViewer.pm @@ -30,15 +30,37 @@ use WeBWorK::Utils::PODParser; sub PODindex ($c) { my $pgRoot = $c->ce->{pg_dir}; - my $podFiles = Pod::Simple::Search->new->inc(0)->limit_re(qr/^doc|^lib|^macros/)->survey($pgRoot); + my $docFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/doc"); + my $macroFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/macros"); + my $libFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/lib"); - my $sections = {}; - for (sort keys %$podFiles) { - my $section = $_ =~ s/::.*$//r; - push(@{ $sections->{$section} }, $podFiles->{$_} =~ s!^$pgRoot/$section/!!r); + my $docs = []; + for (sort keys %$docFiles) { + push(@$docs, $docFiles->{$_} =~ s!^$pgRoot/!!r); } - return $c->render('ContentGenerator/PODViewer', sections => $sections, sidebar_title => $c->maketext('Categories')); + my $macros = {}; + for (sort keys %$macroFiles) { + my $macro = $macroFiles->{$_} =~ s!^$pgRoot/macros/(.+)/.+$!$1!r; + if ($macro =~ /^$pgRoot/) { + push(@$docs, $macroFiles->{$_} =~ s!^$pgRoot/!!r); + } else { + push(@{ $macros->{$macro} }, $macroFiles->{$_} =~ s!^$pgRoot/macros/$macro/!!r); + } + } + + my $libs = []; + for (sort keys %$libFiles) { + push(@$libs, $libFiles->{$_} =~ s!^$pgRoot/lib/!!r); + } + + return $c->render( + 'ContentGenerator/PODViewer', + docs => $docs, + macros => $macros, + libs => $libs, + sidebar_title => $c->maketext('Categories') + ); } sub renderPOD ($c) { diff --git a/templates/ContentGenerator/PODViewer.html.ep b/templates/ContentGenerator/PODViewer.html.ep index 89804f5fa6..416486dc49 100644 --- a/templates/ContentGenerator/PODViewer.html.ep +++ b/templates/ContentGenerator/PODViewer.html.ep @@ -6,26 +6,62 @@ % lib => maketext('Libraries'), % macros => maketext('Macros') % ); +% my %macro_names = ( + % answers => maketext('Answers'), + % contexts => maketext('Contexts'), + % core => maketext('Core'), + % deprecated => maketext('Deprecated'), + % graph => maketext('Graph'), + % math => maketext('Math'), + % misc => maketext('Miscellaneous'), + % parsers => maketext('Parsers'), + % ui => maketext('User Interface') +% ); % -% for my $section (sort keys %$sections) { - % content_for toc => begin - <%= link_to $section_names{$section} => "#$section", class => 'nav-link' %> +% content_for pod_links => begin +

<%= $section_names{doc} %>

+
+ % for (@$docs) { + % my $link_name = $_ =~ s!^(doc|macros)/!!r; + <%= link_to $link_name, 'pod_viewer', { filePath => "$_" }, + class => 'list-group-item list-group-item-action' =%> + % } +
+

<%= $section_names{macros} %>

+% end +% for my $macro (qw(core contexts parsers answers graph math ui misc deprecated)) { + % content_for macros_toc => begin + <%= link_to $macro_names{$macro} => "#macro-$macro", class => 'nav-link' %> % end - % content_for subjects => begin -

<%= $section_names{$section} %>

+ % content_for pod_links => begin +

<%= $macro_names{$macro} %>

- % for (@{ $sections->{$section} }) { - % my $link_name = $_; - % $link_name = $1 =~ s!/!::!gr if $link_name =~ m/^(.*)\.pm$/; - <%= link_to $link_name, 'pod_viewer', { filePath => "$section/$_" }, + % for (@{ $macros->{$macro} }) { + <%= link_to $_, 'pod_viewer', { filePath => "macros/$macro/$_" }, class => 'list-group-item list-group-item-action' =%> % }
% end % } +% content_for pod_links => begin +

<%= $section_names{lib} %>

+
+ % for (@$libs) { + % my $link_name = $_; + % $link_name = $1 =~ s!/!::!gr if $link_name =~ m/^(.*)\.pm$/; + <%= link_to $link_name, 'pod_viewer', { filePath => "lib/$_" }, + class => 'list-group-item list-group-item-action' =%> + % } +
+% end % content_for sidebar => begin % end -<%= content 'subjects' %> +<%= content 'pod_links' %> From 74b77134556b907a9b003e5ada30c649d23eda33 Mon Sep 17 00:00:00 2001 From: Jaimos Skriletz Date: Sat, 23 Nov 2024 21:14:21 -0700 Subject: [PATCH 2/3] Add bin scripts to the wiki PG POD index. --- bin/dev_scripts/generate-ww-pg-pod.pl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bin/dev_scripts/generate-ww-pg-pod.pl b/bin/dev_scripts/generate-ww-pg-pod.pl index b5a1074d45..b416721432 100755 --- a/bin/dev_scripts/generate-ww-pg-pod.pl +++ b/bin/dev_scripts/generate-ww-pg-pod.pl @@ -106,8 +106,8 @@ sub process_dir { my $sections = $is_pg - ? [ doc => 'Documentation', macros => 'Macros', lib => 'Libraries' ] - : [ bin => 'Scripts', doc => 'Documentation', lib => 'Libraries' ]; + ? [ doc => 'Documentation', bin => 'Scripts', macros => 'Macros', lib => 'Libraries' ] + : [ bin => 'Scripts', doc => 'Documentation', lib => 'Libraries' ]; my $macros = $is_pg ? [ core => 'Core', From cf64d0c43fe163c79742962a3a0959265724c208 Mon Sep 17 00:00:00 2001 From: Jaimos Skriletz Date: Sat, 23 Nov 2024 22:06:40 -0700 Subject: [PATCH 3/3] Don't limit macros to predefined lists. To keep from having to update the list each time a macro directory is added/removed/changed, just sort the macros by their directory alphabetically. There is still a hash of macro names to allow both translated or custom names instead of using the directory as its name, but any directory that isn't in the list will also be included without updating the list. --- bin/dev_scripts/PODtoHTML.pm | 33 ++++++++++--------- bin/dev_scripts/generate-ww-pg-pod.pl | 25 ++------------ .../pod-templates/category-index.mt | 7 ++-- templates/ContentGenerator/PODViewer.html.ep | 4 +-- 4 files changed, 24 insertions(+), 45 deletions(-) diff --git a/bin/dev_scripts/PODtoHTML.pm b/bin/dev_scripts/PODtoHTML.pm index f71a22a5bc..6a7925a35b 100644 --- a/bin/dev_scripts/PODtoHTML.pm +++ b/bin/dev_scripts/PODtoHTML.pm @@ -31,11 +31,21 @@ use POSIX qw(strftime); use WeBWorK::Utils::PODParser; our @sections = ( - bin => 'Scripts', - conf => 'Config Files', doc => 'Documentation', + bin => 'Scripts', + macros => 'Macros', lib => 'Libraries', - macros => 'Macros' +); +our %macro_names = ( + answers => 'Answers', + contexts => 'Contexts', + core => 'Core', + deprecated => 'Deprecated', + graph => 'Graph', + math => 'Math', + misc => 'Miscellaneous', + parsers => 'Parsers', + ui => 'User Interface' ); sub new { @@ -43,21 +53,16 @@ sub new { my $class = ref $invocant || $invocant; my @section_list = ref($o{sections}) eq 'ARRAY' ? @{ $o{sections} } : @sections; - my @macros_list = ref($o{macros}) eq 'ARRAY' ? @{ $o{macros} } : (); my $section_hash = {@section_list}; - my $macros_hash = {@macros_list}; my $section_order = [ map { $section_list[ 2 * $_ ] } 0 .. $#section_list / 2 ]; - my $macros_order = @macros_list ? [ map { $macros_list[ 2 * $_ ] } 0 .. $#macros_list / 2 ] : []; delete $o{sections}; - delete $o{macros}; my $self = { %o, idx => {}, section_hash => $section_hash, section_order => $section_order, - macros_hash => $macros_hash, - macros_order => $macros_order, + macros_hash => {}, }; return bless $self, $class; } @@ -140,12 +145,7 @@ sub update_index { if ($subdir eq 'macros') { $idx->{macros} = []; if ($pod_name =~ m!^(.+)/(.+)$!) { - my $macros = $self->{macros_hash}; - if ($macros->{$1}) { - push @{ $idx->{$1} }, [ $html_rel_path, $2 ]; - } else { - warn "no macro for '$pod_name'\n"; - } + push @{ $self->{macros_hash}{$1} }, [ $html_rel_path, $2 ]; } else { push @{ $idx->{doc} }, [ $html_rel_path, $pod_name ]; } @@ -171,7 +171,8 @@ sub write_index { sections => $self->{section_hash}, section_order => $self->{section_order}, macros => $self->{macros_hash}, - macros_order => $self->{macros_order}, + macros_order => [ sort keys %{ $self->{macros_hash} } ], + macro_names => \%macro_names, date => strftime('%a %b %e %H:%M:%S %Z %Y', localtime) } ); diff --git a/bin/dev_scripts/generate-ww-pg-pod.pl b/bin/dev_scripts/generate-ww-pg-pod.pl index b416721432..9024801fb5 100755 --- a/bin/dev_scripts/generate-ww-pg-pod.pl +++ b/bin/dev_scripts/generate-ww-pg-pod.pl @@ -96,39 +96,18 @@ sub process_dir { my $source_dir = shift; return unless $source_dir =~ /\/webwork2$/ || $source_dir =~ /\/pg$/; - my $is_pg = $source_dir =~ /\/pg$/; my $dest_dir = $source_dir; - $dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ unless $is_pg; - $dest_dir =~ s/^$pg_root/$output_dir\/pg/ if $is_pg; + $dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ if ($source_dir =~ /\/webwork2$/); + $dest_dir =~ s/^$pg_root/$output_dir\/pg/ if ($source_dir =~ /\/pg$/); remove_tree($dest_dir); make_path($dest_dir); - my $sections = - $is_pg - ? [ doc => 'Documentation', bin => 'Scripts', macros => 'Macros', lib => 'Libraries' ] - : [ bin => 'Scripts', doc => 'Documentation', lib => 'Libraries' ]; - my $macros = $is_pg - ? [ - core => 'Core', - contexts => 'Contexts', - parsers => 'Parsers', - answers => 'Answers', - graph => 'Graph', - math => 'Math', - ui => 'User Interface', - misc => 'Miscellaneous', - deprecated => 'Deprecated' - ] - : []; - my $htmldocs = PODtoHTML->new( source_root => $source_dir, dest_root => $dest_dir, template_dir => "$webwork_root/bin/dev_scripts/pod-templates", dest_url => $base_url, - sections => $sections, - macros => $macros, verbose => $verbose ); $htmldocs->convert_pods; diff --git a/bin/dev_scripts/pod-templates/category-index.mt b/bin/dev_scripts/pod-templates/category-index.mt index 96895c9117..a5d980d599 100644 --- a/bin/dev_scripts/pod-templates/category-index.mt +++ b/bin/dev_scripts/pod-templates/category-index.mt @@ -25,15 +25,14 @@ % % my ($index, $macro_index, $content, $macro_content) = ('', '', '', ''); % for my $macro (@$macros_order) { - % next unless defined $pod_index->{$macro}; % my $new_index = begin - <%= $macros->{$macro} %> + <%= $macro_names->{$macro} // $macro %> % end % $macro_index .= $new_index->(); % my $new_content = begin -

<%= $macros->{$macro} %>

+

<%= $macro_names->{$macro} // $macro %>

- % for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$macro} }) { + % for my $file (sort { $a->[1] cmp $b->[1] } @{ $macros->{$macro} }) { <%= $file->[1] %> % }
diff --git a/templates/ContentGenerator/PODViewer.html.ep b/templates/ContentGenerator/PODViewer.html.ep index 416486dc49..1383095d5f 100644 --- a/templates/ContentGenerator/PODViewer.html.ep +++ b/templates/ContentGenerator/PODViewer.html.ep @@ -29,9 +29,9 @@

<%= $section_names{macros} %>

% end -% for my $macro (qw(core contexts parsers answers graph math ui misc deprecated)) { +% for my $macro (sort keys %$macros) { % content_for macros_toc => begin - <%= link_to $macro_names{$macro} => "#macro-$macro", class => 'nav-link' %> + <%= link_to $macro_names{$macro} // $macro => "#macro-$macro", class => 'nav-link' %> % end % content_for pod_links => begin

<%= $macro_names{$macro} %>