prodockit 0.41.0

What's Changed

• docs: reorganize authoring guide for beginners by @buckwem in #513
• Document and align authoring configuration by @buckwem in #516
• Expand the project maintenance guide by @buckwem in #517
• Reorganise documentation around author and maintainer workflows by @buckwem in #522
• Release 0.41.0 by @buckwem in #523

Full Changelog: prodockit-v0.40.0...prodockit-v0.41.0

prodockit 0.40.0

• Added: prodockit template-sync --push finishes a sync where the
  pipeline can see it (#502).

  --apply stops at staged, on its own branch, and that publishes
  nothing: both hosts build only from the default branch, so a sync
  sitting on a template-update-... branch produces no pipeline and no
  rebuilt site even after you commit and push it. --push commits,
  merges into the branch your host builds from, and pushes - showing
  what it will do and waiting for a yes first.

  It assumes you merge your own work, with no merge request in the way.
  A project that gates its default branch should use --apply alone and
  raise a merge request from the update branch.

• Fixed: a stale checkout beside a project no longer stops
  template-sync (#500).

  A checkout beside the project wins over fetching, which is right for
  somebody editing the template and their project together - but it won
  unconditionally, so an old clone taken before the template carried a
  manifest stopped the command outright, with a usable copy one fetch
  away. A sibling now has to carry a manifest to be preferred, and the
  run says which checkout it passed over.

• Fixed: the installation page lists every extension (#504).

  It explained how to enable an extension and then named four of the
  nine. prodockit.tables, .tree, .steps, .bibliography and
  .index had each arrived with an entry point and a documentation page
  without reaching the one page a new reader goes to first. A test now
  treats the entry points as the authority, so a registered extension
  cannot go undocumented again.

• Changed: the template-sync manual covers a finished sync, not just
  --apply (#503).

  What to do with a .new sidecar and how to tell "you edited this"
  from "you never received this update"; that --force takes exact
  paths one flag at a time; that a second run branches again; and that
  committing alone changes nothing on the host.

• Added: \ref{id} resolves a captioned figure or table, not only a
  heading (#506).

  A reference to a figure renders its label - Figure 3.1 - linked to
  the figure, and updates itself when figures are added or moved. Until
  now the number had to be typed by hand beside a \ref that could not
  resolve it, so a document said "Figure 3.1" in prose while the figure
  itself was numbered by the stylesheet, with nothing keeping the two in
  step.

  Figures and tables count separately, and both take the page's chapter
  number - the same numbering the caption shows, so a reference and its
  target always agree. Numbered in the same pass that numbers headings,
  which is where the chapter number already exists.

  A caption reference is its label alone, where a heading reference
  keeps its name: "the components in Figure 3.1" reads badly as "Figure
  3.1 Component Model", while a bare "1.1" says nothing about where a
  reader is being sent.

prodockit 0.39.0

• Added: prodockit template-sync, which brings a project back into
  step with the template it came from
  (#495,
  #498).

  A project generated from a template is a copy, not a link. It starts
  ageing immediately - the template gains a CI fix, a stylesheet rule, a
  newer pin - and nothing says so, because nothing breaks. The site
  still builds and the document simply looks slightly unlike everyone
  else's.

  prodockit template-sync           # report; writes no project file
  prodockit template-sync --apply   # branch, write, stage, do not commit

  What is written is decided by a manifest in the template, not by the
  command. The report, its figures and its bibliography are never
  written and never even read, so a sync cannot lose your writing. A
  template-owned file you have edited is kept, with the template's
  version written beside it as .new to compare; --force takes the
  template's copy for a named file.

  The template is fetched into a per-user cache, so no checkout of it is
  needed. A project on Surrey's GitLab tracks the Surrey mirror and
  everything else the GitHub copy, unless --github, --surrey or
  --template-path says otherwise. A host that cannot be reached is a
  third answer rather than a failure - the run continues on the cached
  copy and says that it may be behind.

  Built for repeated use through a project rather than once at the
  start. A run with nothing to do says so and creates no branch; a
  .new sidecar already holding the template's bytes is not rewritten;
  and the recorded baseline moves forward even when a template release
  changes only how files are classified.

  Every run appends its full account - always the --verbose form, and
  including runs that failed - to .prodockit-template.log, which the
  command adds to .gitignore itself.

prodockit 0.38.0

A minor rather than a patch: three tables features change what an author writes, not only what was broken.

Added

Multi-row table headers, merged cells and rotated headings (#474). A Markdown table has one header row and no syntax for a second, so a heading needing two lines was written as a body row - and stopped repeating across pages, since only <thead> repeats. {: .header } moves the row where it belongs, colspan/rowspan come from attr_list directly, and {: rotate=270 width="1.8em" height="105pt" } turns a heading at 90 or 270 - width is required, since rotating without it renders the heading in a full-width column and looks like it worked.

{: .compact } for a table with many short columns (#489). The theme holds every header cell to a 5rem minimum width and 1.25em of padding either side, so a column holding H is as wide as one holding a sentence. One marker drops both, on a header cell, and applies to the PDF too - measured 57% over width becoming a fit on a real 14-column table.

Fixed

A sized table no longer looks like a different component (#490). Setting a column width took the table out of the theme's entire table style, not just the width control, rebuilding the gap with the PDF's own look - full grey grid, hard-coded border colour wrong in dark mode. It now keeps the theme's appearance, confirmed by comparing computed style against an unsized table on the same page.

A captioned figure is no longer narrower than the text around it (#485) - HTML's own <figure> margin was never reset, insetting a width="100%" image 30pt a side in the PDF while the same markup filled the column on the website. Reaches captioned tables too, since a table caption is a <figure>.

An image is no longer drawn off the edge of the paper (#480) - the PDF stylesheet had no equivalent of the website's img { max-width: 100% }, so anything wider than about 627px overflowed the page, unclamped.

A directory tree is indented by one number, and set tighter (#486) - two thirds of a 98px step was accidental theme margin leaking through, now measured rather than reviewed.

The test suite no longer asks the real internet (#476) - fetch-based site/Pages probes were going to github.io/api.github.com/pages.surrey.ac.uk for real, explaining two CI failures that passed on an unchanged re-run. Verified with off-machine sockets refused: 1200 pass, same as with them open.

A hung CI job now fails in minutes rather than hours (#478) - no job set timeout-minutes, so a dead apt-get mirror could hold a runner for the full six-hour default rather than the nine-to-thirty-eight seconds the step actually takes.

The PDF build no longer announces a stage it does not run (#482) - a three-stage build was still calling itself [4/4], left over from a deleted post-processing step.

Docs

prodockit.steps has a page of its own (#471) - the only user-facing extension without one, previously documented only in a docstring pointing at a page that never existed.

Full notes: changelog

prodockit 0.37.0

A minor rather than a patch: two of these change what an author writes, not only what was broken.

Added

prodockit.tree - a directory listing that looks like one (#379).

/// tree
docs/ - the documentation source tree
  index.md - the cover page
  stylesheets/ - CSS for both outputs
zensical.toml - project configuration
///

Indentation is the structure, a trailing / marks a directory, and - starts an optional description. Nothing else is typed, so the icon and the emphasis cannot disagree with what an entry actually is - which a hand-written list has no way to prevent.

Icons come from the project's own set: the block emits a shortcode and whatever icon extension the project already uses renders it, Lucide's folder and file by default. directory_icon/file_icon name others.

Ragged indentation is refused rather than guessed at: a listing is read for its shape, so an entry attached to the wrong parent is a diagram that is wrong and looks right.

Changed

prodockit-table-rotated is now landscape-page (#469), and works for any content - a table, a diagram, an image. There is no alias: a document still using the old class silently stops getting a landscape page rather than erroring, which is why this is a minor version.

Fixed

A landscape page is displayed landscape (#469). The block was always laid out on a landscape page box - that is what makes its pagination and repeating header rows work - and the finished page was then given the PDF's own rotation flag, which a reader honours by showing a landscape page as portrait with the content sideways. Measured before and after: 595x842 (portrait) /Rotate=270 became 842x595 (landscape) /Rotate=0, from an identical page box.

An inline SVG icon is no longer clipped in the PDF. prodockit.pdf.html serialised each <svg> straight from BeautifulSoup, which had parsed the page as HTML and lowercased viewBox to viewbox. SVG attribute names are case-sensitive, so the icon lost the coordinate system it scales into and WeasyPrint drew it at native size, clipped by its own box - a folder icon with its right-hand side sliced off. This affects every icon in every prodockit PDF, not only the new trees.

Full notes: changelog

prodockit 0.36.4

Six fixes, most found by running the bootstrap on a real Windows machine against Surrey's GitLab.

Two stages stopped waiting on things nobody could see

The Ubuntu VS Code install no longer stops for a dialog (#428). The .deb asks whether to add the Microsoft apt repository. apt install -y does not answer that - -y agrees to apt's own questions, not a package's debconf ones - and bootstrap captures its subprocesses, so a clean Ubuntu run simply stopped, looking no different from slow work. The answer is preseeded before the install, so it is part of what the reader approves rather than something they meet alone.

The site and Pages probes ask their URL with Python (#449). Both made an HTTP request by starting curl, which cost three fixes that were never really about curl: it arrived four stages after the first check that wanted it, it was told to write to /dev/null on a platform without one, and a curl typed at a PowerShell prompt resolved to Invoke-WebRequest and looked like an absent program. urllib needs nothing installed, anywhere, at any point in the run. Redirects are deliberately not followed: a 302 is how a login-walled site is recognised as published.

The rest are about telling the truth on screen

The project stage says which address it built its URL from (#441). A GitLab group keeps Name and URL as separate fields and renaming changes only the Name, so a group reading assessment-commtest-2026 in the breadcrumb went on serving git at comm058-2026. Detected and reported with a worked example, rather than guessed at - the real path cannot be read without credentials, and guessing would trade a visible failure for a silent wrong answer.

The installation requirements match what the project declares (#372). Markdown was recorded at >= 3.4 long after the floor moved to 3.10.3, pymdown-extensions was missing entirely, and weasyprint and pandoc were filed as the same kind of thing when one is a pip install away and the other has no Python package at all.

Unassessed work is no longer asked for a course code (#458) it never uses - it was asked one question before anything knew whether the work was assessed.

A .pdf-only image is centred (#462). display: block took it out of the one rule positioning it, so it sat flush left under its own centred caption.

Full notes: changelog

prodockit 0.36.3

Two changes about versions that nothing was watching.

Changed

Pandoc is pinned on Windows, and a differing local pandoc is named (#454). Only Ubuntu pinned it - macOS and Windows took whatever the package manager served, so a machine bootstrap had just set up ran 3.10.2 while every build in this family pins 3.10.1. Pandoc decides how the PDF renders, so that difference is silent by construction: both builds succeed and only the document disagrees.

Windows now installs --version, as Ubuntu always has. macOS cannot - Homebrew has no way to install an old pandoc - so the check says when the local version differs rather than failing, which on that platform would leave a stage no reader could ever clear. A pandoc too old to render correctly still fails, because that one is fixable.

prodockit pins watches prodockit itself (prodockit-template#173). Its absence from the managed set had exactly the consequence the set exists to prevent: prodockit-template sat two releases behind with nothing noticing, and adding it immediately found prodockit-userguide on prodockit[index]==0.21.0, fifteen behind. Moving either needed -p prodockit typed by hand - the step nobody remembers.

Safe in prodockit's own repository, where the name is the project's identity rather than a dependency: the pattern requires a version operator after the name, so name = "prodockit" and the adjacent version are not declarations.

Full notes: changelog

prodockit 0.36.2

Four fixes. Three are one cause seen from different angles: a process already running never receives the PATH an installer has just set, so a bare command name fails on exactly the machine that has the software.

Fixed

Pandoc and Node reported missing while installed (#450). Both checks ran a bare pandoc/node and so saw only this process's PATH. A winget install sets the machine's PATH; a running process does not get it. The stage then offered to install what was already there, winget answered "already up to date", and the check failed again - so the run could not move on. git and VS Code had been given full-path resolution in #390 and #424; these two never were.

sync-repo could not find git (#451). It invoked git by bare name and died with could not run git: [WinError 2] on the same stale PATH. The Jinja macros and the source bundle had the same exposure. All of them now resolve through one shared list of install locations, so the stages and the commands cannot hold two answers about the same machine.

A sync check that could not run was reported as a difference (#451). sync-repo --check exits non-zero both for "there is a difference" and for "I could not look", and the stage said "the project config still needs syncing" to both - naming a cause nobody had established, and sending the reader to run something that would not have fixed it. It now says what actually stopped the check.

The site stage described the wrong host's interface (#444). Every instruction was a literal about GitHub, so GitLab readers were sent looking for a gear beside 'About' and a Settings > Pages that do not exist there. One was worse than merely wrong: it said the site "will be public", true of GitHub and false of GitLab, where a private project's site stays behind the instance's own sign-in - contradicting what the project stage had told the same reader about the same project.

Full notes: changelog

prodockit 0.36.1

Two stops in a Windows run against Surrey GitLab, the message that makes a third one diagnosable, and the Zensical pin.

Fixed

The first push no longer forces over a host-created README (#442). A repository created with "initialize with a README" holds a commit the project's history does not, so an ordinary push is rejected. That was answered with --force-with-lease, which GitLab refuses outright on a protected branch - the rule is about the operation, not the target - so the one case the force existed for was also the case most likely to be blocked. The host's commit is now merged in with -s ours: same tree, fast-forward push, nothing forced and nothing overwritten.

The site probe can run on Windows (#443). It discarded the response body into /dev/null, which Windows has not got; curl tries to create the file, fails, and exits 23. The stage reported "could not check ... the probe did not run" about a site that was serving, on every retry.

Changed

The project stage quotes what the host said (#439). A reader who had just created the project saw the same words on every retry with nothing new to work from. The host's own reply distinguishes what the stage cannot: a project at another path, a group you cannot see into, and a key the host will not accept each need something different from you.

Zensical pinned to 0.0.55 (from 0.0.53). The PDF is byte-identical; 23 pages differ by exactly the generator tag and the bundle filename; stylesheets and workers are byte-identical, so nothing rendered changes.

Full notes: changelog

prodockit 0.36.0

The Surrey configure questions changed shape, from a day of running them.

Changed

• The assessment question comes before the year, and the stage question is numbered (#437).

  The year question explains itself in terms of SRA and LSA, and nothing before it had said what those are - the question that introduces them, and lists them, came afterwards. The stage question also arrived without a number of its own, so a reader counting down met a question that was not in the count.

  5/7 Is this an assessed assignment? [Y/n]: y
  
      1. First
      2. SRA
      3. LSA
  6/7 Which stage is it being assessed at? [1, 2 or 3]: 2
  
  7/7 What year does the module start in? A semester 2 module should be the
      year after the Christmas break. For SRA and LSA the year should be the
      year prior to the year the retake is being assessed. [2026]:
  

• Unassessed work is asked for its group and its repository name (#437), offered as <your login> and report-<your login>:

  5/7 Is this an assessed assignment? [Y/n]: n
  6/7 The group or namespace the project lives under [mb0105]:
  7/7 The name of the repository, and of the folder it lands in here [report-mb0105]:
  

  It has no cohort group to go to and no attempt to record, so a year and a stage were two questions with nothing behind them. Deriving a name from a course code is right for a cohort an examiner reads down a column of; work nobody is marking is named by whoever owns it.

• The questions are worded as they were asked for (#420). The login question had lost the example that made it answerable - a student logs in with ab1234@surrey.ac.uk, so "the six-character ID" asks about something they may never have typed alone. The year question had lost the rule for a resit and gained a different one.

Fixed

• A first run printed the stage list over the details it had just told you to note down (#433). The namespace and the repository name are the only two values a reader carries from this command to a browser, and twenty-three stage lines printed after them scrolled both away. It stops there now, where --configure already did.

• The ssh-agent step ended the run without looking (#435). 0.34.0 stopped that step looping and overshot: the moment you said the service was started, the run ended and asked you to start again. A started service usually is visible to the next command that looks - ssh-add opens the agent's pipe afresh each time - so the check is given its chance, and a run that can carry on carries on. The message no longer suggests opening a new window, which never did anything running the command again would not.

Full notes in the changelog.