Restyle the SOCRATES docs with the shared PROTEUS theme - #27
Merged
Conversation
SOCRATES still carried the earlier navy and orange styling while PROTEUS and the visual language moved on, so our module sites no longer read as one product. I am bringing SOCRATES onto the shared theme. `stylesheets/extra.css` is now a verbatim copy of the theme stylesheet released as visual language 1.3.0, and I do not edit it here, so taking a later release is a plain copy. Everything this site needs on top of it lives in the new `stylesheets/layout.css`, which holds the correction set our module sites share; it is the same block in each of them, so they stay comparable. `stylesheets/diagram.css` goes with it, since the shared block carries the same rules, while `stylesheets/subtitle.css` stays: the subtitle is this site's own and belongs nowhere else. The brand fonts are served from `stylesheets/fonts/`, so the pages no longer request Inter and JetBrains Mono from Google on every load. The header mark and favicon become the phase glyph, and the light and dark palettes swap order so the toggle shows the mode you are in. Two fixes on the framework page. It showed the PROTEUS wordmark twice, because `#gh-light-mode-only` and `#gh-dark-mode-only` are honoured by GitHub's markdown renderer and ignored everywhere else; the two images now carry the `logo-light` and `logo-dark` classes that the stylesheet switches on the active scheme, and they load from the same CDN path as the schematic below them rather than being copied in. The getting-started page offered a card leading to a contributing guide at `Community/CONTRIBUTING.md`. This repository has no such page and never has, so the card led nowhere; it now points at the framework's contributing guide. Redirect it if you would rather it went somewhere else. The contact address moves to dev@proteus-framework.org in the footer and on the contact page. I removed the retired wordmark and favicon files, which nothing else referenced.
Our module front pages each opened differently: some led with the badge row, one wedged a logo between the title and the badges, and this one was a hand-centred landing page with the table of contents and the navigation hidden. Read side by side they looked like separate projects. This gives SOCRATES the opening the Aragog and PROTEUS pages already use: the module name as the heading, the subtitle spelling out the acronym beneath it, the badges under that, then a lead sentence saying what SOCRATES is and where it sits in the framework. The page keeps its contents pane and its navigation, like every other module page. The wrapper the page was built inside carried a class that no stylesheet ever defined, so it goes. The subtitle rule moves into the shared block of `stylesheets/layout.css`, since the front-page subtitle is now something any module page can use, and `stylesheets/subtitle.css` goes with it. Nothing is dropped: every badge, link and paragraph is the one that was there before.
…e paint Two things about how a module page arrives. The landing pages no longer show the navigation menu down the left. It listed the two pages a reader is already looking at, took a third of the width from the text, and made our sites look unlike each other depending on which had one. PROTEUS and SOCRATES already hid it there; this is the rest of them. Pages inside a section keep it, since that menu is how a reader moves between the pages of a section and there is nothing else offering that. The colour scheme is now settled in the document head rather than after the page has parsed. The markup we serve always carries whichever palette is listed first, and the theme works out the reader's real setting from a script at the end of the body, so a reader whose setting is the other one watched the page load in the wrong palette and then flip. A few lines in the head read the setting, and a hand-picked scheme if there is one, and stamp it on the body the moment the body exists.
…e paint The menu down the left of a landing page listed both the page you were on and the getting-started page. Now the front page is the Home section itself, so the menu beside it holds the one entry a reader actually wants from there, the getting-started guide. On SOCRATES that guide had been sitting in the tab bar as a section of its own, which put it a level above where it sits everywhere else; it now lives under Home like the others, and the tab bars match across our modules. Separately, the colour scheme is settled in the document head rather than after the page has parsed. The markup we serve always carries whichever palette is listed first, and the theme works out the reader's real setting from a script at the end of the body, so a reader whose setting is the other one watched the page load in the wrong palette and then flip. A few lines in the head read the setting, and a hand-picked scheme if there is one, and stamp it on the body the moment the body exists.
The menu beside a landing page now reads the same on every module: an About entry that opens the front page, and the getting-started guide beneath it. Most of our sites already had that shape. SOCRATES kept its guide in the tab bar as a section of its own, a level above where the others put it, so its tab bar had an entry none of the rest did; the guide now sits under Home and the tab bars match. VULCAN called its entry Quick start while everyone else said Getting started, and the module template had no getting-started page at all to put there, so it gets one to fill in. The colour scheme is settled in the document head rather than after the page has parsed. The markup we serve always carries whichever palette is listed first, and the theme works out the reader's real setting from a script at the end of the body, so a reader whose setting is the other one watched the page load in the wrong palette and then flip. A few lines in the head read the setting, and a hand-picked scheme if there is one, and stamp it on the body the moment the body exists.
The badge row differed on every module: different set, different order, some as centred HTML, one pulling coverage from a gist while the repository reports to codecov, one carrying a PyPI badge nobody else had, and one down to two. They now read the same way everywhere, in one order: licence, docs, coverage, unit tests, integration tests. Where a module cannot support a badge it does not get one, rather than showing a broken or unknown value. VULCAN has no nightly workflow, so it has no integration-tests badge, and its coverage still comes from the gist its tests publish because it does not report to codecov. SOCRATES has no test workflows at all, so it carries the licence and docs badges only. Every badge in this change was fetched before it was committed; each one returns a real state rather than "invalid" or "unknown".
The script that settles the colour scheme before first paint looked the reader's choice up under the bare key `__palette`. The theme scopes its storage keys by path and writes to `<path>.__palette`, so the lookup never matched, the branch that honours a hand-picked scheme was dead, and a reader who had chosen the scheme opposite their system setting got the system one painted first and the theme's correction a moment later. That is the flip this was supposed to remove, just moved onto a different reader. It now reads through the theme's own getter, so it cannot drift from wherever the theme decides to keep that value. The comment above it also claimed the theme resolves the scheme at the end of the body; it does so near the top, and the comment no longer says otherwise. The header script no longer hardcodes a module name to find its own docs home. MORS was pointing at SPIDER's path and JANUS carried two names, one of them Zalmoxis's, so on those sites clicking the title left the site. The theme already points the logo at each site's home, so the script now takes the address from there and no page needs to know its own name. The contact address moves to dev@proteus-framework.org in the code of conduct and, where it appears there, the copyright line of the licence. The first row of the contact table now reads GitHub Discussions everywhere, which is what PROTEUS calls it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Brings the SOCRATES documentation site onto the shared PROTEUS theme, so it matches PROTEUS, JANUS, Morrigan and fwl-io instead of the earlier navy and orange styling.
Why
Our module sites had drifted apart visually. The shared theme works by every site dropping in the same stylesheet unchanged, so the sites read as one product and a future theme update is a plain copy everywhere.
Changes
docs/stylesheets/extra.cssis a verbatim copy of the stylesheet released as visual language 1.3.0 and is not edited here.docs/stylesheets/layout.cssis new and holds everything this site needs on top of it, as one block that is identical across our module sites. It replacesdocs/stylesheets/proteus_theme.cssanddocs/stylesheets/diagram.css, whose rules the shared block carries.docs/stylesheets/subtitle.cssstays, since the subtitle is this site's own.docs/stylesheets/fonts/, so the pages no longer request Inter and JetBrains Mono from Google on every load.#gh-light-mode-onlyand#gh-dark-mode-onlyare honoured by GitHub markdown and ignored everywhere else. The images now carry thelogo-lightandlogo-darkclasses the stylesheet switches, loaded from the same CDN path as the schematic below them.Community/CONTRIBUTING.md. This repository has no such page and never has, so the card led nowhere; it now points at the framework's contributing guide, which returns 200. Redirect it if you would rather it went elsewhere.dev@proteus-framework.orgin the footer and on the contact page.Testing
zensical build --cleanis clean, no warnings. Verified against the built output: no page requests a font from Google, the theme stylesheets load in cascade order, the framework page emits one wordmark per scheme, and no page references a retired mark.extra.csshashes identical to thev1.3.0tag.The documentation-PDF page references
assets/pdfs/socrates_userguide.pdfandsocrates_techguide.pdf, which are absent from a local build and look broken. They are not:.github/workflows/docs.yamlbuilds both from LaTeX and copies them into place, so they exist in the published site. Left untouched.