From 9fde3e5380082bb1e6aa871556aca6f5f0085715 Mon Sep 17 00:00:00 2001 From: Jaimos Skriletz Date: Tue, 5 Nov 2024 23:03:31 -0700 Subject: [PATCH] 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 9c7810a55b..87ee1dc616 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 b0e6e06d99..8b5827ea04 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' %>