From 52994ad4db3ff46d75c792eb869f3fec7e81d110 Mon Sep 17 00:00:00 2001 From: CSchank Date: Tue, 15 Sep 2026 11:14:41 -0400 Subject: [PATCH 1/2] List the documents in the order they are meant to be read The index page listed documents alphabetically by folder, which put the checklists first and the problem statement in the middle. They are now listed in waterfall order, taken from the Final Documentation (Revision 1) list in the course outline. That order is deliberately not the order the documents are written in: the V&V plan is written in week 8 and the design in week 10, but the design is read first. Listing them this way reinforces the rational design process the documentation presents, and makes the set easier to follow for a reader from outside the course. Sections carry readable titles, so that projMngmnt and CDs read as Project Management and Custom Documents. Within a section the order is explicit where alphabetical was wrong: the requirements document before its FAQ, architecture before detailed design, and the productivity reports in chronological rather than alphabetical order. The checklists mirror the deliverables, so they follow the same order as the sections. A folder not named in the ordering is listed after the known ones, alphabetically, so adding a document cannot make it disappear from the page. site/ is added to the workflow path filters, since a change to the page template previously did not trigger a run and so was never published. It is ignored when deciding what to rebuild, because it changes the page rather than any PDF. Co-Authored-By: Claude Opus 5 (1M context) --- .github/scripts/build_index.py | 86 +++++++++++++++++++++++++++++-- .github/scripts/select_docs.py | 5 +- .github/workflows/latex-pages.yml | 4 +- site/index.html | 4 ++ site/style.css | 6 +++ 5 files changed, 99 insertions(+), 6 deletions(-) diff --git a/.github/scripts/build_index.py b/.github/scripts/build_index.py index 83569e7..6d35f76 100644 --- a/.github/scripts/build_index.py +++ b/.github/scripts/build_index.py @@ -20,6 +20,84 @@ PDF_LIST_MARKER = "" GENERATED_MARKER = "" +# The documents are listed in waterfall order, which is not the order in which +# the course creates them: the V&V plan is written before the design, but is +# read after it. Listing them this way reinforces the rational design process +# the course asks students to fake, and makes the documentation easier to +# follow for a reader from outside the course. +# +# Taken from the Final Documentation (Revision 1) list in the course outline. +# A directory not named here is listed after these, alphabetically, so adding +# a document folder cannot make it disappear from the page. +SECTION_ORDER = [ + ("ProblemStatementAndGoals", "Problem Statement and Goals"), + ("DevelopmentPlan", "Development Plan"), + ("SRS", "Requirements (SRS)"), + ("SRS-Volere", "Requirements, Volere template"), + ("SRS-Meyer", "Requirements, Meyer template"), + ("HazardAnalysis", "Hazard Analysis"), + ("Design", "Design"), + ("VnVPlan", "Verification and Validation Plan"), + ("VnVReport", "Verification and Validation Report"), + ("UserGuide", "User Guide"), + ("CDs", "Custom Documents"), + ("ReflectAndTrace", "Reflection and Traceability"), + ("projMngmnt", "Project Management"), + ("Checklists", "Checklists"), +] + +# Within a section, documents that should not be alphabetical. The checklists +# mirror the deliverables, so they follow the same order as the sections above; +# the design documents go architecture first, then detailed design. +FILE_ORDER = { + "Checklists": [ + "GettingStarted-Checklist.pdf", + "ProbState-Checklist.pdf", + "DevPlan-Checklist.pdf", + "SRS-Checklist.pdf", + "SRS-SciComp-Checklist.pdf", + "HA-Checklist.pdf", + "MG-Checklist.pdf", + "MIS-Checklist.pdf", + "VnV-Checklist.pdf", + "POC-Checklist.pdf", + "Code-Checklist.pdf", + "Writing-Checklist.pdf", + "FinalDoc-Checklist.pdf", + ], + "Design": ["MG.pdf", "MIS.pdf"], + # The requirements document first, then the questions about it. + "SRS": ["SRS.pdf", "SRS-FAQ.pdf"], + # Chronological: proof of concept, then revision 0, then final. + "projMngmnt": [ + "POC_Productivity_Rep.pdf", + "Rev0_Productivity_Rep.pdf", + "Final_Productivity_Rep.pdf", + ], +} + + +def section_rank(directory): + """Position of a section, with unlisted ones sorted after the known ones.""" + for index, (name, _title) in enumerate(SECTION_ORDER): + if name == directory: + return (0, index, "") + return (1, 0, directory.lower()) + + +def section_title(directory): + for name, title in SECTION_ORDER: + if name == directory: + return title + return directory + + +def file_rank(directory, filename): + order = FILE_ORDER.get(directory) + if order and filename in order: + return (0, order.index(filename), "") + return (1, 0, filename.lower()) + def git_last_updated(repo_relative_path): """Commit time of a path, or None when git knows nothing about it.""" @@ -86,10 +164,12 @@ def collect(public_dir, tracked_dir): def render(sections): lines = [] - for section in sorted(sections): - lines.append("

%s

" % escape(section)) + for section in sorted(sections, key=section_rank): + lines.append("

%s

" % escape(section_title(section))) lines.append("