Skip to content

Add a workflow to generate and publish PG POD and sample problem documentation. #1346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Add a workflow to generate and publish PG POD and sample problem documentation. #1346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions .github/workflows/generate-and-publish-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: Generate and Publish PG POD and Sample Problem Documentation

on:
# Execute the workflow anytime something is merged into or pushed to main.
push:
branches:
- main

# This allows this workflow to be triggered manually from the actions tab.
workflow_dispatch:

jobs:
generate-documentation:
runs-on: ubuntu-24.04

steps:
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends --no-install-suggests \
pandoc \
libmojolicious-perl \
libpandoc-wrapper-perl \
libpod-parser-perl

- name: Checkout pg code
uses: actions/checkout@v4
with:
path: pg

- name: Create output directory
run: mkdir /home/runner/work/pg/pg/documentation

- name: Generate sample problem documentation
run: |
perl pg/bin/parse-problem-doc.pl \
--problem-dir=/home/runner/work/pg/pg/pg/tutorial/sample-problems \
--out-dir=/home/runner/work/pg/pg/documentation/sampleproblems \
--pod-base-url=/pg/pod \
--sample-problem-base-url=/pg/sampleproblems

- name: Generate POD
run: perl pg/bin/generate-pg-pod.pl --output-dir=documentation/pod --base-url=/pg/pod/ --home-url=/pg

- name: Generate search data
run: perl pg/bin/generate-search-data.pl --out-file=documentation/sample-problem-search-data.json

- name: Copy assets
run: |
cp /home/runner/work/pg/pg/pg/tutorial/templates/index.html \
/home/runner/work/pg/pg/documentation/
cp /home/runner/work/pg/pg/pg/htdocs/js/SampleProblemViewer/documentation-search.js \
/home/runner/work/pg/pg/documentation/

- name: Upload documentation html
uses: actions/upload-pages-artifact@v3
with:
path: documentation

publish-documentation:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

# Set the permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages.
permissions:
pages: write
id-token: write

runs-on: ubuntu-24.04
needs: generate-documentation

steps:
- name: Publish to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
94 changes: 94 additions & 0 deletions assets/pod-templates/category-index.mt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<!DOCTYPE html>
<html lang="en" dir="ltr">
%
<head>
<meta charset='UTF-8'>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><%= $title %></title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="<%= $dest_url %>/assets/podviewer.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/js/bootstrap.bundle.min.js" defer></script>
<script src="<%= $dest_url %>/assets/podviewer.js" defer></script>
</head>
%
<body>
<div class="pod-header navbar navbar-dark bg-primary px-3 position-fixed border-bottom border-dark">
<div class="container-fluid d-flex flex-column d-md-block">
<h1 class="navbar-brand fw-bold fs-5 me-auto me-md-0 mb-2 mb-md-0"><%= $title %></h1>
<button class="navbar-toggler d-md-none me-auto" type="button" data-bs-toggle="offcanvas"
data-bs-target="#sidebar" aria-controls="sidebar" aria-label="Toggle Sidebar">
<span class="navbar-toggler-icon"></span>
</button>
</div>
</div>
%
% my ($index, $macro_index, $content, $macro_content) = ('', '', '', '');
% for my $macro (@$macros_order) {
% my $new_index = begin
<a href="#macro-<%= $macro %>" class="nav-link"><%= $macro_names->{$macro} // $macro %></a>
% end
% $macro_index .= $new_index->();
% my $new_content = begin
<h3><a href="#_podtop_" id="macro-<%= $macro %>"><%= $macro_names->{$macro} // $macro %></a></h3>
<div class="list-group mb-2">
% for my $file (sort { $a->[1] cmp $b->[1] } @{ $macros->{$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">
% 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
% $content .= $new_content->();
% }
%
<aside class="offcanvas-md offcanvas-start border-end border-dark position-fixed" tabindex="-1"
id="sidebar" aria-labelledby="sidebar-label">
<div class="offcanvas-header">
<h2 class="offcanvas-title" id="sidebar-label">Index</h2>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#sidebar"
aria-label="Close">
</button>
</div>
<div class="offcanvas-body p-md-3 w-100">
<nav class="nav flex-column w-100">
<a href="<%= $home_url %>" class="nav-link"><%= $home_url_link_name %></a>
<a href="https://wiki.openwebwork.org/wiki/WeBWorK_Main_Page" class="nav-link">WeBWorK Wiki</a>
<hr>
<%= $index =%>
</nav>
</div>
</aside>
<div class="pod-page-container d-flex">
<div class="container-fluid p-3 h-100" id="_podtop_">
<%= $content =%>
<p class="mt-3">Generated <%= $date %></p>
</div>
</div>
</body>
%
</html>
55 changes: 55 additions & 0 deletions assets/pod-templates/pod.mt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<!DOCTYPE html>
<html lang="en" dir="ltr">
%
<head>
<meta charset='UTF-8'>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><%= $title %></title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="<%= $dest_url %>/assets/podviewer.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/js/bootstrap.bundle.min.js" defer></script>
<script src="<%= $dest_url %>/assets/podviewer.js" defer></script>
</head>
%
<body>
<div class="pod-header navbar navbar-dark bg-primary px-3 position-fixed border-bottom border-dark">
<div class="container-fluid d-flex flex-column d-md-block">
<h1 class="navbar-brand fw-bold fs-5 me-auto me-md-0 mb-2 mb-md-0"><%= $title %></h1>
<button class="navbar-toggler d-md-none me-auto" type="button" data-bs-toggle="offcanvas"
data-bs-target="#sidebar" aria-controls="sidebar" aria-label="Toggle Sidebar">
<span class="navbar-toggler-icon"></span>
</button>
</div>
</div>
<aside class="offcanvas-md offcanvas-start border-end border-dark position-fixed" tabindex="-1"
id="sidebar" aria-labelledby="sidebar-label">
<div class="offcanvas-header">
<h2 class="offcanvas-title" id="sidebar-label">Index</h2>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#sidebar"
aria-label="Close">
</button>
</div>
<div class="offcanvas-body p-md-3 w-100">
<nav>
<ul class="nav flex-column w-100">
<li class="nav-item">
<a href="<%= $home_url %>" class="nav-link p-0"><%= $home_url_link_name %></a>
</li>
<li class="nav-item">
<a href="https://wiki.openwebwork.org/wiki/WeBWorK_Main_Page"
class="nav-link p-0">WeBWorK Wiki</a>
</li>
<li><hr></li>
<%= $index->join('') =%>
</ul>
</nav>
</div>
</aside>
<div class="pod-page-container d-flex">
<div class="container-fluid p-3 h-100" id="_podtop_">
<%= $content =%>
</div>
</div>
</body>
%
</html>
Loading