Skip to content

Commit

Permalink
Split up macros on PODViewer index page.
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@somiaj
somiaj committed Nov 24, 2024
1 parent ceca849 commit 9fde3e5
Show file tree
Hide file tree
Showing 5 changed files with 149 additions and 23 deletions.
22 changes: 21 additions & 1 deletion bin/dev_scripts/PODtoHTML.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down Expand Up @@ -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";
Expand All @@ -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)
}
);
Expand Down
25 changes: 23 additions & 2 deletions bin/dev_scripts/generate-ww-pg-pod.pl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
33 changes: 30 additions & 3 deletions bin/dev_scripts/pod-templates/category-index.mt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,45 @@
</div>
</div>
%
% 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
<a href="#macro-<%= $macro %>" class="nav-link"><%= $macros->{$macro} %></a>
% end
% $macro_index .= $new_index->();
% my $new_content = begin
<h3><a href="#_podtop_" id="macro-<%= $macro %>"><%= $macros->{$macro} %></a></h3>
<div class="list-group mb-2">
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$macro} }) {
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action"><%= $file->[1] %></a>
% }
</div>
% end
% $macro_content .= $new_content->();
% }
% for my $section (@$section_order) {
% next unless defined $pod_index->{$section};
% my $new_index = begin
<a href="#<%= $section %>" class="nav-link"><%= $sections->{$section} %></a>
% if ($section eq 'macros') {
<div class="nav flex-column ms-3">
<%= $macro_index %>
</div>
% }
% end
% $index .= $new_index->();
% my $new_content = begin
<h2><a href="#_podtop_" id="<%= $section %>"><%= $sections->{$section} %></a></h2>
<div class="list-group mb-2">
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) {
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action"><%= $file->[1] %></a>
% if ($section eq 'macros') {
<%= $macro_content =%>
% } else {
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) {
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action">
<%= $file->[1] %>
</a>
% }
% }
</div>
% end
Expand Down
34 changes: 28 additions & 6 deletions lib/WeBWorK/ContentGenerator/PODViewer.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
58 changes: 47 additions & 11 deletions templates/ContentGenerator/PODViewer.html.ep
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<h2><a href="#_podtop_" id="doc"><%= $section_names{doc} %></a></h2>
<div class="list-group mb-2">
% for (@$docs) {
% my $link_name = $_ =~ s!^(doc|macros)/!!r;
<%= link_to $link_name, 'pod_viewer', { filePath => "$_" },
class => 'list-group-item list-group-item-action' =%>
% }
</div>
<h2><a href="#_podtop_" id="macros"><%= $section_names{macros} %></a></h2>
% 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
<h2><a href="#_podtop_" id="<%= $section %>"><%= $section_names{$section} %></a></h2>
% content_for pod_links => begin
<h3><a href="#_podtop_" id="macro-<%= $macro %>"><%= $macro_names{$macro} %></a></h3>
<div class="list-group mb-2">
% 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' =%>
% }
</div>
% end
% }
% content_for pod_links => begin
<h2><a href="#_podtop_" id="lib"><%= $section_names{lib} %></a></h2>
<div class="list-group mb-2">
% 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' =%>
% }
</div>
% end
% content_for sidebar => begin
<nav class="nav flex-column w-100">
<%= content 'toc' %>
<%= link_to $section_names{doc} => '#doc', class => 'nav-link' %>
<%= link_to $section_names{macros} => '#macros', class => 'nav-link' %>
<div class="nav flex-column ms-3">
<%= content 'macros_toc' %>
</div>
<%= link_to $section_names{lib} => '#lib', class => 'nav-link' %>
</nav>
% end
<%= content 'subjects' %>
<%= content 'pod_links' %>

0 comments on commit 9fde3e5

Please sign in to comment.