Ks/docs

[stuitje]

Description

This PR updates JANUS' documentation with Zensical and adds substantial documentation using the Diataxis structure.

New pages

• Installation guide : covers SOCRATES installation via tools/get_socrates.sh, JANUS installation, data download, etc
• First-run tutorial: walks through running examples/demo_runaway_greenhouse.py
• Testing guide
• Model overview: model overview based on both the papers and the code located in Explanations/. Please take a look here as I struggled a bit. All feedback welcome.
• Publications list of JANUS papers located in Reference/
• Getting started page (same as usual)
• PROTEUS Framework overview to introduce other modules
• Community pages such as contact.md

Tools

• tools/get_socrates.sh: new helper script to clone and build SOCRATES, with build output logged to build.log, and only real errors printed to terminal
• MkDocs configuration for Zensical theme including CSS overrides, content tabs, etc

[Copilot]

Pull request overview

This PR restructures and expands the JANUS documentation using a Diátaxis-style layout, updates the MkDocs/Zensical-based site configuration and theme assets, and adds automation for building docs and installing SOCRATES.

Changes:

• Add new documentation sections/pages (How-to, Tutorials, Explanations, Reference, Community) and reorganize navigation accordingly.
• Introduce tools/get_socrates.sh helper script for cloning/building SOCRATES with logging.
• Update docs site build/deploy configuration (MkDocs config + GitHub Pages workflow) and add theme CSS/JS overrides.

Reviewed changes

Copilot reviewed 18 out of 23 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
tools/get_socrates.sh	New helper script to clone/build SOCRATES with logging and simplified terminal output
mkdocs.yml	Reworked navigation + Material theme features, plugins, and extra assets for the new docs structure
docs/stylesheets/extra.css	Adds PROTEUS/JANUS branding and UI styling overrides for Material
docs/stylesheets/footnotes.css	Footnote styling tweaks and reduced spacing around titles/images
docs/proteus-framework.md	Adds a PROTEUS framework overview landing page within JANUS docs
docs/javascripts/header-links.js	Adds header click behavior to route users to a chosen “docs home”
docs/index.md	Updates docs homepage content and contribution links
docs/getting_started.md	Replaces install-centric page with a “quick path” + task chooser cards
docs/Tutorials/first_run.md	Adds a runnable “first run” tutorial based on the demo script
docs/Reference/publications.md	Adds a publications reference page
docs/How-to/test.md	Adds a testing guide describing how to run and interpret test coverage
docs/How-to/installation.md	Adds a standalone installation guide for JANUS + SOCRATES
docs/How-to/documentation.md	Adds documentation development instructions (local build/preview + structure)
docs/Explanations/model.md	Adds a detailed physical/model overview (equations + references)
docs/Community/contact.md	Adds contact/community channels page
docs/Community/CONTRIBUTING.md	Includes root CONTRIBUTING.md into docs site
docs/Community/CODE_OF_CONDUCT.md	Includes root CODE_OF_CONDUCT.md into docs site
docs/overrides/partials/extrahead.html	Removes the previous extrahead override (favicon handling moved to theme config)
README.md	Updates docs badge/linking and surfaces docs workflow + tests badge
.gitignore	Ignores built documentation output (site/) and local SOCRATES clone (socrates/)
.github/workflows/docs.yaml	Switches docs deployment to GitHub Pages artifact-based flow using Zensical build

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The workflow installs a bespoke set of doc build dependencies instead of using the repo’s declared docs extras (pyproject.toml [project.optional-dependencies].docs). This can easily drift (e.g., missing mkdocs-material required by theme: material in mkdocs.yml). Consider installing the package with its docs extra (or a pinned requirements file) to keep CI and local builds consistent.

Suggested change

	- run: pip install zensical markdown-include pymdown-extensions mkdocstrings mkdocstrings-python
	- run: pip install ".[docs]"

[Copilot]

In the SSH auth check, an exit code of 0 is treated as success in the comment, but use_ssh remains false, so the script will still select the HTTPS URI even though SSH worked. Consider setting use_ssh=true for both exit codes 0 and 1 (or invert the logic to explicitly detect the failure case only).

Suggested change

	: # exit 0 would be unusual, but treat as success
	use_ssh=true # exit 0 would be unusual, but treat as success

[Copilot]

The build output filtering doesn't match the comment: tee -a "$logfile" still echoes the full build output to the terminal. If the goal is to only show matched error lines on the terminal, redirect tee's stdout away from the terminal (or avoid tee and write directly to the logfile while separately printing errors).

Suggested change

	./build_code 2>&1 | tee -a "$logfile" | grep -iE "error:|fatal error:|undefined reference|cannot find|ld returned" >&2
	build_exit=${PIPESTATUS[0]}
	./build_code \
	> >(tee -a "$logfile" >/dev/null) \
	2> >(tee -a "$logfile" | grep -iE "error:|fatal error:|undefined reference|cannot find|ld returned" >&2)
	build_exit=$?

[nichollsh]

Overall looks great! Thanks, Karen. I have some minor suggestions below to fix some typos.

We should think about how to consolidate these various get_socrates scripts, since there are now multiple versions across several different repositories. We could potentially host them all in the SOCRATES repo itself, and access the get_socrates.sh file with curl piped to sh.

[stuitje]

Overall looks great! Thanks, Karen. I have some minor suggestions below to fix some typos.

We should think about how to consolidate these various get_socrates scripts, since there are now multiple versions across several different repositories. We could potentially host them all in the SOCRATES repo itself, and access the get_socrates.sh file with curl piped to sh.

Thanks Harrison, I see now I was a bit tired, so thanks for seeing the typos.
And yes that might be a good solution.

[nichollsh]

Thanks, @stuitje! Happy for this to be merged.

[timlichtenberg]

Great addition, thanks Karen! :)