Skip to content

Commit 0cdb18e

Browse files
somiajsomiaj
committed
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.
1 parent df4b848 commit 0cdb18e

File tree

5 files changed

+149
-23
lines changed

5 files changed

+149
-23
lines changed

‎bin/dev_scripts/PODtoHTML.pm

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,15 +43,21 @@ sub new {
4343
my $class = ref $invocant || $invocant;
4444

4545
my @section_list = ref($o{sections}) eq 'ARRAY' ? @{ $o{sections} } : @sections;
46+
my @macros_list = ref($o{macros}) eq 'ARRAY' ? @{ $o{macros} } : ();
4647
my $section_hash = {@section_list};
48+
my $macros_hash = {@macros_list};
4749
my $section_order = [ map { $section_list[ 2 * $_ ] } 0 .. $#section_list / 2 ];
50+
my $macros_order = @macros_list ? [ map { $macros_list[ 2 * $_ ] } 0 .. $#macros_list / 2 ] : [];
4851
delete $o{sections};
52+
delete $o{macros};
4953

5054
my $self = {
5155
%o,
5256
idx => {},
5357
section_hash => $section_hash,
5458
section_order => $section_order,
59+
macros_hash => $macros_hash,
60+
macros_order => $macros_order,
5561
};
5662
return bless $self, $class;
5763
}
@@ -131,7 +137,19 @@ sub update_index {
131137
$subdir =~ s|/.*$||;
132138
my $idx = $self->{idx};
133139
my $sections = $self->{section_hash};
134-
if (exists $sections->{$subdir}) {
140+
if ($subdir eq 'macros') {
141+
$idx->{macros} = [];
142+
if ($pod_name =~ m!^(.+)/(.+)$!) {
143+
my $macros = $self->{macros_hash};
144+
if ($macros->{$1}) {
145+
push @{ $idx->{$1} }, [ $html_rel_path, $2 ];
146+
} else {
147+
warn "no macro for '$pod_name'\n";
148+
}
149+
} else {
150+
push @{ $idx->{doc} }, [ $html_rel_path, $pod_name ];
151+
}
152+
} elsif (exists $sections->{$subdir}) {
135153
push @{ $idx->{$subdir} }, [ $html_rel_path, $pod_name ];
136154
} else {
137155
warn "no section for subdir '$subdir'\n";
@@ -152,6 +170,8 @@ sub write_index {
152170
pod_index => $self->{idx},
153171
sections => $self->{section_hash},
154172
section_order => $self->{section_order},
173+
macros => $self->{macros_hash},
174+
macros_order => $self->{macros_order},
155175
date => strftime('%a %b %e %H:%M:%S %Z %Y', localtime)
156176
}
157177
);

‎bin/dev_scripts/generate-ww-pg-pod.pl

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,18 +96,39 @@ sub process_dir {
9696
my $source_dir = shift;
9797
return unless $source_dir =~ /\/webwork2$/ || $source_dir =~ /\/pg$/;
9898

99+
my $is_pg = $source_dir =~ /\/pg$/;
99100
my $dest_dir = $source_dir;
100-
$dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ if ($source_dir =~ /\/webwork2$/);
101-
$dest_dir =~ s/^$pg_root/$output_dir\/pg/ if ($source_dir =~ /\/pg$/);
101+
$dest_dir =~ s/^$webwork_root/$output_dir\/webwork2/ unless $is_pg;
102+
$dest_dir =~ s/^$pg_root/$output_dir\/pg/ if $is_pg;
102103

103104
remove_tree($dest_dir);
104105
make_path($dest_dir);
105106

107+
my $sections =
108+
$is_pg
109+
? [ doc => 'Documentation', macros => 'Macros', lib => 'Libraries' ]
110+
: [ bin => 'Scripts', doc => 'Documentation', lib => 'Libraries' ];
111+
my $macros = $is_pg
112+
? [
113+
core => 'Core',
114+
contexts => 'Contexts',
115+
parsers => 'Parsers',
116+
answers => 'Answers',
117+
graph => 'Graph',
118+
math => 'Math',
119+
ui => 'User Interface',
120+
misc => 'Miscellaneous',
121+
deprecated => 'Deprecated'
122+
]
123+
: [];
124+
106125
my $htmldocs = PODtoHTML->new(
107126
source_root => $source_dir,
108127
dest_root => $dest_dir,
109128
template_dir => "$webwork_root/bin/dev_scripts/pod-templates",
110129
dest_url => $base_url,
130+
sections => $sections,
131+
macros => $macros,
111132
verbose => $verbose
112133
);
113134
$htmldocs->convert_pods;

‎bin/dev_scripts/pod-templates/category-index.mt

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,45 @@
2323
</div>
2424
</div>
2525
%
26-
% my ($index, $content) = ('', '');
26+
% my ($index, $macro_index, $content, $macro_content) = ('', '', '', '');
27+
% for my $macro (@$macros_order) {
28+
% next unless defined $pod_index->{$macro};
29+
% my $new_index = begin
30+
<a href="#macro-<%= $macro %>" class="nav-link"><%= $macros->{$macro} %></a>
31+
% end
32+
% $macro_index .= $new_index->();
33+
% my $new_content = begin
34+
<h3><a href="#_podtop_" id="<%= $macro %>"><%= $macros->{$macro} %></a></h3>
35+
<div class="list-group mb-2">
36+
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$macro} }) {
37+
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action"><%= $file->[1] %></a>
38+
% }
39+
</div>
40+
% end
41+
% $macro_content .= $new_content->();
42+
% }
2743
% for my $section (@$section_order) {
2844
% next unless defined $pod_index->{$section};
2945
% my $new_index = begin
3046
<a href="#<%= $section %>" class="nav-link"><%= $sections->{$section} %></a>
47+
% if ($section eq 'macros') {
48+
<div class="nav flex-column ms-3">
49+
<%= $macro_index %>
50+
</div>
51+
% }
3152
% end
3253
% $index .= $new_index->();
3354
% my $new_content = begin
3455
<h2><a href="#_podtop_" id="<%= $section %>"><%= $sections->{$section} %></a></h2>
3556
<div class="list-group mb-2">
36-
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) {
37-
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action"><%= $file->[1] %></a>
57+
% if ($section eq 'macros') {
58+
<%= $macro_content =%>
59+
% } else {
60+
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) {
61+
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action">
62+
<%= $file->[1] %>
63+
</a>
64+
% }
3865
% }
3966
</div>
4067
% end

‎lib/WeBWorK/ContentGenerator/PODViewer.pm

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,37 @@ use WeBWorK::Utils::PODParser;
3030
sub PODindex ($c) {
3131
my $pgRoot = $c->ce->{pg_dir};
3232

33-
my $podFiles = Pod::Simple::Search->new->inc(0)->limit_re(qr/^doc|^lib|^macros/)->survey($pgRoot);
33+
my $docFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/doc");
34+
my $macroFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/macros");
35+
my $libFiles = Pod::Simple::Search->new->inc(0)->survey("$pgRoot/lib");
3436

35-
my $sections = {};
36-
for (sort keys %$podFiles) {
37-
my $section = $_ =~ s/::.*$//r;
38-
push(@{ $sections->{$section} }, $podFiles->{$_} =~ s!^$pgRoot/$section/!!r);
37+
my $docs = [];
38+
for (sort keys %$docFiles) {
39+
push(@$docs, $docFiles->{$_} =~ s!^$pgRoot/!!r);
3940
}
4041

41-
return $c->render('ContentGenerator/PODViewer', sections => $sections, sidebar_title => $c->maketext('Categories'));
42+
my $macros = {};
43+
for (sort keys %$macroFiles) {
44+
my $macro = $macroFiles->{$_} =~ s!^$pgRoot/macros/(.+)/.+$!$1!r;
45+
if ($macro =~ /^$pgRoot/) {
46+
push(@$docs, $macroFiles->{$_} =~ s!^$pgRoot/!!r);
47+
} else {
48+
push(@{ $macros->{$macro} }, $macroFiles->{$_} =~ s!^$pgRoot/macros/$macro/!!r);
49+
}
50+
}
51+
52+
my $libs = [];
53+
for (sort keys %$libFiles) {
54+
push(@$libs, $libFiles->{$_} =~ s!^$pgRoot/lib/!!r);
55+
}
56+
57+
return $c->render(
58+
'ContentGenerator/PODViewer',
59+
docs => $docs,
60+
macros => $macros,
61+
libs => $libs,
62+
sidebar_title => $c->maketext('Categories')
63+
);
4264
}
4365

4466
sub renderPOD ($c) {

‎templates/ContentGenerator/PODViewer.html.ep

Lines changed: 47 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,62 @@
66
% lib => maketext('Libraries'),
77
% macros => maketext('Macros')
88
% );
9+
% my %macro_names = (
10+
% answers => maketext('Answers'),
11+
% contexts => maketext('Contexts'),
12+
% core => maketext('Core'),
13+
% deprecated => maketext('Deprecated'),
14+
% graph => maketext('Graph'),
15+
% math => maketext('Math'),
16+
% misc => maketext('Miscellaneous'),
17+
% parsers => maketext('Parsers'),
18+
% ui => maketext('User Interface')
19+
% );
920
%
10-
% for my $section (sort keys %$sections) {
11-
% content_for toc => begin
12-
<%= link_to $section_names{$section} => "#$section", class => 'nav-link' %>
21+
% content_for pod_links => begin
22+
<h2><a href="#_podtop_" id="doc"><%= $section_names{doc} %></a></h2>
23+
<div class="list-group mb-2">
24+
% for (@$docs) {
25+
% my $link_name = $_ =~ s!^(doc|macros)/!!r;
26+
<%= link_to $link_name, 'pod_viewer', { filePath => "$_" },
27+
class => 'list-group-item list-group-item-action' =%>
28+
% }
29+
</div>
30+
<h2><a href="#_podtop_" id="macros"><%= $section_names{macros} %></a></h2>
31+
% end
32+
% for my $macro (qw(core contexts parsers answers graph math ui misc deprecated)) {
33+
% content_for macros_toc => begin
34+
<%= link_to $macro_names{$macro} => "#macro-$macro", class => 'nav-link' %>
1335
% end
14-
% content_for subjects => begin
15-
<h2><a href="#_podtop_" id="<%= $section %>"><%= $section_names{$section} %></a></h2>
36+
% content_for pod_links => begin
37+
<h3><a href="#_podtop_" id="macro-<%= $macro %>"><%= $macro_names{$macro} %></a></h3>
1638
<div class="list-group mb-2">
17-
% for (@{ $sections->{$section} }) {
18-
% my $link_name = $_;
19-
% $link_name = $1 =~ s!/!::!gr if $link_name =~ m/^(.*)\.pm$/;
20-
<%= link_to $link_name, 'pod_viewer', { filePath => "$section/$_" },
39+
% for (@{ $macros->{$macro} }) {
40+
<%= link_to $_, 'pod_viewer', { filePath => "macros/$macro/$_" },
2141
class => 'list-group-item list-group-item-action' =%>
2242
% }
2343
</div>
2444
% end
2545
% }
46+
% content_for pod_links => begin
47+
<h2><a href="#_podtop_" id="lib"><%= $section_names{lib} %></a></h2>
48+
<div class="list-group mb-2">
49+
% for (@$libs) {
50+
% my $link_name = $_;
51+
% $link_name = $1 =~ s!/!::!gr if $link_name =~ m/^(.*)\.pm$/;
52+
<%= link_to $link_name, 'pod_viewer', { filePath => "lib/$_" },
53+
class => 'list-group-item list-group-item-action' =%>
54+
% }
55+
</div>
56+
% end
2657
% content_for sidebar => begin
2758
<nav class="nav flex-column w-100">
28-
<%= content 'toc' %>
59+
<%= link_to $section_names{doc} => '#doc', class => 'nav-link' %>
60+
<%= link_to $section_names{macros} => '#macros', class => 'nav-link' %>
61+
<div class="nav flex-column ms-3">
62+
<%= content 'macros_toc' %>
63+
</div>
64+
<%= link_to $section_names{lib} => '#lib', class => 'nav-link' %>
2965
</nav>
3066
% end
31-
<%= content 'subjects' %>
67+
<%= content 'pod_links' %>

0 commit comments

Comments
 (0)