Documentation overhaul

[stuitje]

Description

This PR overhaul's VULCAN's documentation, and closes #17. It improves the style, adds reference pages such as a config reference and API reference and adds a detailed model overview + proteus coupling pages. A quick summary of the documentation changes:

Edited pages

• index.md: improved look, description and key features added. Note that I like the animation, so I left it, but an improved/high-resolution version would be nice in the future.
• How-to/chem_networks.md: improved readability and explains where network files live and which are available.
• How-to/installation.md: improved style/readability
• Reference/bibliography: improved style and added fastchem papers
• Tutorials/first_run.md: renamed from quickstart, improved style and fixed problems
• proteus_framework.md: renamed from submodules, now also refers to PROTEUS coupling page

New pages

• quickstart.md: a getting started guide, but renamed because of the get started section on the landing page.
• How-to/use_in_proteus.md: an how-to on how to configure VULCAN in proteus
• Reference/api/: full API reference. classes/methods without docstrings are also shown now, but should get docstrings at some point, see Docstrings update #18
• Reference/config.md Configuration reference
• Reference/constants.md constants reference
• Detailed model overview in Explanations. Follows every method section in Tsai et al. (2021), and links to the code (each mentioned class/file links to the API reference). I tried to do the typography well according to the link @maraattia sent me; hope it is correct :) If not please let me know.
• Explanations/proteus_coupling.md: Explains how VULCAN is integrated into PROTEUS, including a mermaid flowchart.
• fastchem.md: a FastChem credit and information page, also links to fastchem publications. Please check this file! It is at the top level of the navigation, in the horizontal navigation bar at the top.

Other changes

Source modules now have module docstrings (with imports listed) to show nicely in the API reference. I fixed a path issue in plot_vulcan.py. pre-commit fixes.

Validation of changes

I built the documentation locally on Safari, Chrome and Firefox and followed the how-to and tutorial steps myself for verification.

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required

Relevant people

@nichollsh @ipanagiotou02 @timlichtenberg

[Copilot]

Pull request overview

This PR substantially restructures VULCAN’s MkDocs site by adding new how-to, tutorial, explanation, and reference pages (including an mkdocstrings-driven API reference), while also adding/expanding module-level docstrings in src/vulcan/* to support the generated API docs. It also includes a small runtime change in the plotting helper to align with the newer Config/VULCAN_DIR path handling.

Changes:

• Overhauled MkDocs navigation + styling (new pages, new CSS, Mermaid fences, updated nav structure).
• Added extensive new documentation content (tutorials/how-tos/explanations/reference + FastChem + PROTEUS coupling).
• Added module docstrings across core Python modules and adjusted tools/plot_vulcan.py plot output path handling.

Reviewed changes

Copilot reviewed 53 out of 54 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/plot_vulcan.py	Updates plot output directory handling to use Config.plot_dir.
src/vulcan/vulcan.py	Adds module docstring and minor docstring punctuation tweak.
src/vulcan/store.py	Adds module docstring for API docs.
src/vulcan/phy_const.py	Adds module docstring for API docs.
src/vulcan/paths.py	Adds module docstring for API docs.
src/vulcan/op.py	Adds module docstring for API docs.
src/vulcan/make_chem_funs.py	Adds module docstring (but currently disrupts shebang placement).
src/vulcan/logs.py	Adds module docstring for API docs.
src/vulcan/config.py	Adds module docstring for API docs.
src/vulcan/build_atm.py	Adds module docstring for API docs.
src/vulcan/agni.py	Adds module docstring for API docs.
mkdocs.yml	Major docs nav restructure; enables Mermaid fences; tweaks mkdocstrings options; adds CSS.
docs/Tutorials/quickstart.md	Removes old quickstart tutorial page.
docs/Tutorials/index.md	Removes old tutorials index page.
docs/Tutorials/first_run.md	Adds new “first run” tutorial.
docs/submodules.md	Removes old PROTEUS submodules page.
docs/stylesheets/proteus_theme.css	Adds PROTEUS theme styling overrides.
docs/stylesheets/footnotes.css	Adds footnote marker styling.
docs/stylesheets/extra.css	Simplifies CSS but currently contains duplicated blocks.
docs/Reference/constants.md	Adds physical constants reference page.
docs/Reference/config.md	Adds detailed configuration parameter reference page.
docs/Reference/bibliography.md	Expands bibliography into a publications page including FastChem references.
docs/Reference/api/vulcan.md	Adds mkdocstrings page for vulcan.vulcan.
docs/Reference/api/op.md	Adds mkdocstrings page for vulcan.op.
docs/Reference/api/make_chem_funs.md	Adds mkdocstrings page for vulcan.make_chem_funs.
docs/Reference/api/build_atm.md	Adds mkdocstrings page for vulcan.build_atm.
docs/Reference/api/agni.md	Adds mkdocstrings page for vulcan.agni.
docs/Reference/api/config.md	Adds mkdocstrings page for vulcan.config.
docs/Reference/api/paths.md	Adds mkdocstrings page for vulcan.paths.
docs/Reference/api/phy_const.md	Adds mkdocstrings page for vulcan.phy_const.
docs/Reference/api/store.md	Adds mkdocstrings page for vulcan.store.
docs/Reference/api/logs.md	Adds mkdocstrings page for vulcan.logs.
docs/Reference/api/index.md	Adds API overview page and module map.
docs/quickstart.md	Adds a new top-level quickstart landing page.
docs/proteus_framework.md	Adds a new “other PROTEUS modules” landing page with embedded schematic.
docs/index.md	Rebuilds the docs homepage with badges, feature list, and quick links.
docs/How-to/use_in_proteus.md	Adds PROTEUS integration how-to.
docs/How-to/installation.md	Expands/rewrites installation guide (env setup, FastChem build, optional AGNI).
docs/How-to/index.md	Removes old how-to index page.
docs/How-to/chem_network.md	Major rewrite/expansion of chemical network editing guide.
docs/fastchem.md	Adds dedicated FastChem overview and integration page.
docs/Explanations/model_usage.md	Removes old model-usage page (replaced by new explanation set).
docs/Explanations/model_overview.md	Adds model overview page.
docs/Explanations/basic_equations.md	Adds basic equations + numerics page.
docs/Explanations/boundary_conditions.md	Adds boundary conditions page.
docs/Explanations/chemical_networks.md	Adds chemical networks page (currently has a broken link + wrong path note).
docs/Explanations/photochemistry.md	Adds photochemistry explanation page.
docs/Explanations/uv_cross_sections.md	Adds UV cross-sections explanation page.
docs/Explanations/condensation.md	Adds condensation/rainout explanation page.
docs/Explanations/titanium_vanadium.md	Adds Ti/V chemistry explanation page.
docs/Explanations/haze_precursors.md	Adds haze precursors explanation page.
docs/Explanations/proteus_coupling.md	Adds detailed PROTEUS↔VULCAN coupling explanation (with Mermaid flowchart).
.github/workflows/tests.yaml	Renames workflow display name.

Comments suppressed due to low confidence (1)

tools/plot_vulcan.py:37

• plot_dir comes from Config as an absolute path (via VULCAN_DIR), and the repo doesn’t ship an output/ directory. Using os.mkdir(plot_dir) will raise FileNotFoundError when output/ is missing (it only creates the final path element). Also the user-facing message still references vulcan_cfg.py, but configuration now lives in src/vulcan/config.py.

[Copilot]

Pull request overview

Copilot reviewed 74 out of 117 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

tools/plot_vulcan.py:37

• This script now uses vulcan.config.Config (not a legacy vulcan_cfg.py module), so the error message/comment are outdated. Also, os.mkdir(plot_dir) will fail if intermediate directories are missing; os.makedirs(..., exist_ok=True) is safer and matches the main code’s behavior.

[stuitje]

@nichollsh @timlichtenberg this PR is ready for human review.

The pre-commit is still currently failing; there are some docstring issues in the files inside tools/. I didn't change these files, but I ran pre-commit on them earlier, which automatically removed some trailing whitespace and caused them to be part of this PR. I have played around with adding module docstrings a bit, but for some reason, pre-commit keeps failing locally. I think I can figure this out during the review.

[nichollsh]

I would suggest simply excluding the tools/ folder from the pre-commit check. These are mostly legacy files anyway.

[nichollsh]

Looks awesome! The docs build fine on my laptop and the code still runs with the whitespace/syntax changes.

The description of the model in the documentation is accurate, to my understanding of VULCAN. I've also attempted to verify the citations.

I think this level of credit/explanation about FastChem is good. We don't want more detail, and this level of detail is well justified. Thanks for this.

Happy to merge into main when the pre-commit issue is resolved. Perhaps just exclude the tools/ folder to enable this.

[stuitje]

I would suggest simply excluding the tools/ folder from the pre-commit check. These are mostly legacy files anyway.

Thanks Harrison, I think this is a good idea, will implement it :)