Skip to content

Commit ed479a2

Browse files
drgrice1drgrice1
committed
Add a workflow to generate and publish PG POD and sample problem documentation.
This is intended to replace the openwebwork/pg-docs repository. The approach in that repository has some issues. * The workflows must be manually triggered in sequence. * It isn't tied to the PG repository and so can become and in fact is now out of date. * It unnecessarily commits the generated documentation files to a repository as well as publishing them on GitHub pages. * It uses the `bin/dev_script/generate-ww-pg-pod.pl` script from the webwork2 repository to generate the PG and webwork2 POD, and the webwork2 POD should not be on a site that is intended for PG documentation. Furthermore, the generated html POD site does not fit into the PG documentation site well. For, example there is no link to get back to the main PG documentation index page, and it is labeled as WeBorK documentation, not PG documentation. The single workflow added in this pull request runs anytime anything is merged into the main branch. It can also be manually triggered but that generally won't be needed. This means that anytime a new version of PG is released the documentation will automatically be updated for that release. The workflow generates the PG POD and sample problem documentation and publishes the documentation to the PG GitHub pages site at https://openwebwork.github.io/pg. The generated documentation is not committed to a repository. It is published to the pages site, and that is enough. A new `bin/generate-pg-pod.pl` script is added that generates only the PG POD. The generated html is tailored for the PG documentation on GitHub pages. There is some minor redundancy as there are some files that are now in both the webwork2 and PG repositories (needed for both the `generate-ww-pg-pod.pl` and `generate-pg-pod.pl` scripts). However, it certainly would not be a good idea to have the PG repository depend on the webwork2 repository for the `generate-ww-pg-pod.pl` script, and as mentioned that script doesn't really generated the right HTML to begin with. Move the `SampleProblemParser` module into the `WeBWorK::PG` namespace. All of the other modules in the root namespace in the PG repository are directly for problem rendering except this one. It is out of place. So it is now the `WeBWorK::PG::SampleProblemParser` module. Change the options for the `parser-problem-doc.pl` script and the `WeBWorK::PG::SampleProblemParser` module. Using underscores for options is annoying. Underscores require an extra keyboard button press (the shift key), and underscore are not standard for command line options. Also the `pod_root` and `pg_doc_home` options are badly named. The `pod_root` option name seems to indicate it should be the directory location for the POD, but it is a URL. So make that clear by renaming it to `pod-base-url`. The `pg_doc_home` is not the URL for the PG documentation home, but for the sample problem base URL. So rename that to `sample-problem-base-url` (and its shortcut from "h" to "s"). Also change the corresponding variable names in the `SampleProblemParser.pm` module. Copy the PODParser.pm and PODtoHTML.pm modules from the webwork2 repository to lib/WeBWorK/Utils where webwork2 can also use them. Those modules will be deleted from the webwork2 repository. Copy podviewer.css and podviewer.js from the webwork2 repository into htdocs/js/PODViewer, also where webwork2 can use them. The files will be deleted from the webwork2 repository. Copy the bin/dev_scripts/pod-templates category-index.mt and pod.mt files into assets/pod-templates here, and make changes to the files so that they will work for both webwork2 and pg. The files will also be deleted from the webwork2 repository. Add the sample problem and macro POD search to PG docs. The sample problem and macro POD search data is generated by the `WeBWorK::PG::SampleProblemParser::getSearchData` method. This is used by webwork2 and the `bin/generate-search-data.pl` script. The script is very simple. It just calls the method passing in the file name to save the data to. The workflow runs the script and copies the resulting file to the PG github pages site. The `assets/stop-words-en.txt` file is moved here from the webwork2 repository since the `WeBWorK::PG::SampleProblemParser::getSearchData` needs it. The `htdocs/js/SampleProblemViewer/documentation-search.js` is moved from the webwork2 repository (webwork2 uses it from here now), and this is also copied to the PG github pages site in the workflow. It is slightly modified to work for both webwork2 and on the PG github pages site.
1 parent ac640be commit ed479a2

File tree

20 files changed

+2771
-291
lines changed

20 files changed

+2771
-291
lines changed

‎.github/workflows/generate-and-publish-docs.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Generate and Publish PG POD and Sample Problem Documentation
2+
3+
on:
4+
# Execute the workflow anytime something is merged into or pushed to main.
5+
push:
6+
branches:
7+
- main
8+
9+
# This allows this workflow to be triggered manually from the actions tab.
10+
workflow_dispatch:
11+
12+
jobs:
13+
generate-documentation:
14+
runs-on: ubuntu-24.04
15+
16+
steps:
17+
- name: Install dependencies
18+
run: |
19+
sudo apt-get update
20+
sudo apt-get install -y --no-install-recommends --no-install-suggests \
21+
pandoc \
22+
libmojolicious-perl \
23+
libpandoc-wrapper-perl \
24+
libpod-parser-perl
25+
26+
- name: Checkout pg code
27+
uses: actions/checkout@v4
28+
with:
29+
path: pg
30+
31+
- name: Create output directory
32+
run: mkdir /home/runner/work/pg/pg/documentation
33+
34+
- name: Generate sample problem documentation
35+
run: |
36+
perl pg/bin/parse-problem-doc.pl \
37+
--problem-dir=/home/runner/work/pg/pg/pg/tutorial/sample-problems \
38+
--out-dir=/home/runner/work/pg/pg/documentation/sampleproblems \
39+
--pod-base-url=/pg/pod \
40+
--sample-problem-base-url=/pg/sampleproblems
41+
42+
- name: Generate POD
43+
run: perl pg/bin/generate-pg-pod.pl --output-dir=documentation/pod --base-url=/pg/pod/ --home-url=/pg
44+
45+
- name: Generate search data
46+
run: perl pg/bin/generate-search-data.pl --out-file=documentation/sample-problem-search-data.json
47+
48+
- name: Copy assets
49+
run: |
50+
cp /home/runner/work/pg/pg/pg/tutorial/templates/index.html \
51+
/home/runner/work/pg/pg/documentation/
52+
cp /home/runner/work/pg/pg/pg/htdocs/js/SampleProblemViewer/documentation-search.js \
53+
/home/runner/work/pg/pg/documentation/
54+
55+
- name: Upload documentation html
56+
uses: actions/upload-pages-artifact@v3
57+
with:
58+
path: documentation
59+
60+
publish-documentation:
61+
environment:
62+
name: github-pages
63+
url: ${{ steps.deployment.outputs.page_url }}
64+
65+
# Set the permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages.
66+
permissions:
67+
pages: write
68+
id-token: write
69+
70+
runs-on: ubuntu-24.04
71+
needs: generate-documentation
72+
73+
steps:
74+
- name: Publish to GitHub Pages
75+
id: deployment
76+
uses: actions/deploy-pages@v4

‎assets/pod-templates/category-index.mt‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<!DOCTYPE html>
2+
<html lang="en" dir="ltr">
3+
%
4+
<head>
5+
<meta charset='UTF-8'>
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
<title><%= $title %></title>
8+
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">
9+
<link href="<%= $dest_url %>/assets/podviewer.css" rel="stylesheet">
10+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" defer></script>
11+
<script src="<%= $dest_url %>/assets/podviewer.js" defer></script>
12+
</head>
13+
%
14+
<body>
15+
<div class="pod-header navbar navbar-dark bg-primary px-3 position-fixed border-bottom border-dark">
16+
<div class="container-fluid d-flex flex-column d-md-block">
17+
<h1 class="navbar-brand fw-bold fs-5 me-auto me-md-0 mb-2 mb-md-0"><%= $title %></h1>
18+
<button class="navbar-toggler d-md-none me-auto" type="button" data-bs-toggle="offcanvas"
19+
data-bs-target="#sidebar" aria-controls="sidebar" aria-label="Toggle Sidebar">
20+
<span class="navbar-toggler-icon"></span>
21+
</button>
22+
</div>
23+
</div>
24+
%
25+
% my ($index, $macro_index, $content, $macro_content) = ('', '', '', '');
26+
% for my $macro (@$macros_order) {
27+
% my $new_index = begin
28+
<a href="#macro-<%= $macro %>" class="nav-link"><%= $macro_names->{$macro} // $macro %></a>
29+
% end
30+
% $macro_index .= $new_index->();
31+
% my $new_content = begin
32+
<h3><a href="#_podtop_" id="macro-<%= $macro %>"><%= $macro_names->{$macro} // $macro %></a></h3>
33+
<div class="list-group mb-2">
34+
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $macros->{$macro} }) {
35+
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action"><%= $file->[1] %></a>
36+
% }
37+
</div>
38+
% end
39+
% $macro_content .= $new_content->();
40+
% }
41+
% for my $section (@$section_order) {
42+
% next unless defined $pod_index->{$section};
43+
% my $new_index = begin
44+
<a href="#<%= $section %>" class="nav-link"><%= $sections->{$section} %></a>
45+
% if ($section eq 'macros') {
46+
<div class="nav flex-column ms-3">
47+
<%= $macro_index %>
48+
</div>
49+
% }
50+
% end
51+
% $index .= $new_index->();
52+
% my $new_content = begin
53+
<h2><a href="#_podtop_" id="<%= $section %>"><%= $sections->{$section} %></a></h2>
54+
<div class="list-group mb-2">
55+
% if ($section eq 'macros') {
56+
<%= $macro_content =%>
57+
% } else {
58+
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $pod_index->{$section} }) {
59+
<a href="<%= $file->[0] %>" class="list-group-item list-group-item-action">
60+
<%= $file->[1] %>
61+
</a>
62+
% }
63+
% }
64+
</div>
65+
% end
66+
% $content .= $new_content->();
67+
% }
68+
%
69+
<aside class="offcanvas-md offcanvas-start border-end border-dark position-fixed" tabindex="-1"
70+
id="sidebar" aria-labelledby="sidebar-label">
71+
<div class="offcanvas-header">
72+
<h2 class="offcanvas-title" id="sidebar-label">Index</h2>
73+
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#sidebar"
74+
aria-label="Close">
75+
</button>
76+
</div>
77+
<div class="offcanvas-body p-md-3 w-100">
78+
<nav class="nav flex-column w-100">
79+
<a href="<%= $home_url %>" class="nav-link"><%= $home_url_link_name %></a>
80+
<a href="https://wiki.openwebwork.org/wiki/WeBWorK_Main_Page" class="nav-link">WeBWorK Wiki</a>
81+
<hr>
82+
<%= $index =%>
83+
</nav>
84+
</div>
85+
</aside>
86+
<div class="pod-page-container d-flex">
87+
<div class="container-fluid p-3 h-100" id="_podtop_">
88+
<%= $content =%>
89+
<p class="mt-3">Generated <%= $date %></p>
90+
</div>
91+
</div>
92+
</body>
93+
%
94+
</html>

‎assets/pod-templates/pod.mt‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<!DOCTYPE html>
2+
<html lang="en" dir="ltr">
3+
%
4+
<head>
5+
<meta charset='UTF-8'>
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
<title><%= $title %></title>
8+
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">
9+
<link href="<%= $dest_url %>/assets/podviewer.css" rel="stylesheet">
10+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" defer></script>
11+
<script src="<%= $dest_url %>/assets/podviewer.js" defer></script>
12+
</head>
13+
%
14+
<body>
15+
<div class="pod-header navbar navbar-dark bg-primary px-3 position-fixed border-bottom border-dark">
16+
<div class="container-fluid d-flex flex-column d-md-block">
17+
<h1 class="navbar-brand fw-bold fs-5 me-auto me-md-0 mb-2 mb-md-0"><%= $title %></h1>
18+
<button class="navbar-toggler d-md-none me-auto" type="button" data-bs-toggle="offcanvas"
19+
data-bs-target="#sidebar" aria-controls="sidebar" aria-label="Toggle Sidebar">
20+
<span class="navbar-toggler-icon"></span>
21+
</button>
22+
</div>
23+
</div>
24+
<aside class="offcanvas-md offcanvas-start border-end border-dark position-fixed" tabindex="-1"
25+
id="sidebar" aria-labelledby="sidebar-label">
26+
<div class="offcanvas-header">
27+
<h2 class="offcanvas-title" id="sidebar-label">Index</h2>
28+
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#sidebar"
29+
aria-label="Close">
30+
</button>
31+
</div>
32+
<div class="offcanvas-body p-md-3 w-100">
33+
<nav>
34+
<ul class="nav flex-column w-100">
35+
<li class="nav-item">
36+
<a href="<%= $home_url %>" class="nav-link p-0"><%= $home_url_link_name %></a>
37+
</li>
38+
<li class="nav-item">
39+
<a href="https://wiki.openwebwork.org/wiki/WeBWorK_Main_Page"
40+
class="nav-link p-0">WeBWorK Wiki</a>
41+
</li>
42+
<li><hr></li>
43+
<%= $index->join('') =%>
44+
</ul>
45+
</nav>
46+
</div>
47+
</aside>
48+
<div class="pod-page-container d-flex">
49+
<div class="container-fluid p-3 h-100" id="_podtop_">
50+
<%= $content =%>
51+
</div>
52+
</div>
53+
</body>
54+
%
55+
</html>

0 commit comments

Comments
 (0)