Make sure docs cache rebuilds + organise tutorials + document dt_mass_modifiers

docs/Makefile

@@ -228,6 +228,6 @@ pseudoxml:
 
 .PHONY: apidoc
 apidoc:
-	sphinx-apidoc -o api/ ../src/cosmic ../src/cosmic/tests --no-toc --separate --no-headings --force
+	sphinx-apidoc -o api/ ../src/cosmic ../src/cosmic/tests --no-toc --separate --no-headings
 	@echo
 	@echo "APIdoc run is complete."

docs/_static/cosmic-docs.css

@@ -88,17 +88,6 @@ html[data-theme="dark"] .sd-card {
     background-color: #e193ca;
 }
 
-@media (max-width: 720px) {
-    .toms-nav-container {
-        width: 100%;
-        height: auto;
-        grid-template-columns: 100%;
-        grid-template-rows: auto;
-        grid-column-gap: 0;
-        grid-row-gap: 20px;
-    }
-}
-
 #installation h2 {
     font-size: 1.2rem;
 }
@@ -552,4 +541,59 @@ select.form-control {
 
 .link-white {
     color: white!important;
+}
+
+.content:has(.tutorial-card) {
+    width: 100%;
+    padding: 0 7em;
+}
+
+.content:has(.tutorial-card) h1 {
+    text-align: center;
+    margin-left: 100px;
+}
+
+.center {
+    text-align: center;
+}
+
+.tutorial-card {
+    text-align: center!important;
+}
+
+.tutorial-card-title {
+    font-size: 2rem!important;
+    font-weight: bold!important;
+    margin-bottom: 0.5rem!important;
+}
+
+.tutorial-card-link {
+    display: block;
+    padding: .25rem;
+    font-size: 1rem;
+    border-radius: 10px;
+    transition: 300ms;
+    margin: 0 !important;
+}
+
+.tutorial-card-link:hover {
+    background-color: var(--color-brand-primary);
+}
+.tutorial-card-link:hover, .tutorial-card-link:hover a {
+    color: white!important;
+}
+
+@media (max-width: 720px) {
+    .toms-nav-container {
+        width: 100%;
+        height: auto;
+        grid-template-columns: 100%;
+        grid-template-rows: auto;
+        grid-column-gap: 0;
+        grid-row-gap: 20px;
+    }
+
+    .content:has(.tutorial-card) {
+        padding: 0 1em;
+    }
 }

docs/conf.py

@@ -76,6 +76,9 @@
     'remove_config_comments': True,
 }
 
+import matplotlib
+matplotlib.rcParams["savefig.dpi"] = 300
+
 # -- autosummary --------------------------------
 
 autosummary_generate = True
@@ -117,7 +120,7 @@
 
 # General information about the project.
 project = u'cosmic'
-copyright = u'2021, Katie Breivik'
+copyright = u'2019-2026, Katie Breivik, Tom Wagg'
 author = u'Katie Breivik'
 
 # The version info for the project you're documenting, acts as replacement for

docs/create_settings_html.py

@@ -11,6 +11,7 @@
 import json
 import pandas as pd
 from cosmic import __version__ as cosmic_version
+from os.path import exists
 
 # how many versions in the past should we show as badges for when options were added?
 VERSION_CUTOFFS = {
@@ -225,6 +226,15 @@ def version_is_recent(version_string):
     # append this group to the soup (guess who's a poet and didn't even know it)
     soup.select_one(".container-fluid").append(new_group)
 
-    # write the soup out to an HTML file for this category
-    with open(f"_generated/config_insert_{group['category']}.html", "w") as f:
-        f.write(str(soup))
+    # write the soup out to an HTML file for this category (only if changed)
+    out_path = f"_generated/config_insert_{group['category']}.html"
+    content = str(soup)
+    if exists(out_path):
+        with open(out_path) as f:
+            if f.read() == content:
+                print(f"  No changes to {out_path}, skipping write.")
+                continue
+
+    print(f"  Writing settings HTML for category '{group['category']}' to {out_path}...")
+    with open(out_path, "w") as f:
+        f.write(content)

docs/create_whats_new.py

@@ -11,6 +11,7 @@
 
 import re
 from pathlib import Path
+from os.path import exists
 
 def parse_changelog(changelog_path):
     with open(changelog_path, 'r') as f:
@@ -37,29 +38,34 @@ def parse_changelog(changelog_path):
     return parsed_sections
 
 def generate_rst(parsed_sections, output_path):
-    with open(output_path, 'w') as f:
-        f.write("What's New in COSMIC\n")
-        f.write("====================\n\n")
+    lines = ["What's New in COSMIC\n====================\n"]
 
-        for heading, features in parsed_sections:
+    for heading, features in parsed_sections:
+        lines.append(f"v{heading}\n{'-' * (len(heading) + 1)}\n")
 
-            f.write(f"v{heading}\n")
-            f.write(f"{'-' * (len(heading) + 1)}\n\n")
+        # Check if the heading is a version number (e.g., "4.1.0")
+        if re.match(r'^\d+\.\d+\.\d+$', heading):
+            github_link = f"https://github.com/COSMIC-PopSynth/COSMIC/releases/tag/v{heading}"
+            lines.append(f"`GitHub release <{github_link}>`_\n")
 
-            # Check if the heading is a version number (e.g., "4.1.0")
-            if re.match(r'^\d+\.\d+\.\d+$', heading):
-                github_link = f"https://github.com/COSMIC-PopSynth/COSMIC/releases/tag/v{heading}"
-                f.write(f"`GitHub release <{github_link}>`_\n\n")
+        for feature in features:
+            lines.append(feature)
+        lines.append("")
 
-            for feature in features:
-                f.write(feature + "\n")
-            f.write("\n")
+    content = "\n".join(lines)
+    if exists(output_path):
+        with open(output_path) as f:
+            if f.read() == content:
+                print(f"  No changes to {output_path}, skipping write.")
+                return
+
+    print(f"  Writing 'What's New' content to {output_path}...")
+    with open(output_path, "w") as f:
+        f.write(content)
 
 if __name__ == "__main__":
     changelog_path = Path("../changelog.md")
     output_path = Path("_generated/whats_new.rst")
 
     parsed_sections = parse_changelog(changelog_path)
     generate_rst(parsed_sections, output_path)
-
-    print(f"Generated {output_path} from {changelog_path}")

docs/generate_default_bsedict.py

@@ -1,5 +1,6 @@
 import json
 from pathlib import Path
+from os.path import exists
 
 def get_default_BSE_settings(to_python=False):
     """Get a copy of the default BSE settings from the COSMIC settings JSON file"""
@@ -45,33 +46,43 @@ def generate_rst_bsedict(MAX_LINE_LENGTH=80):
 
     indent_str = " " * 8
 
-    with open("_generated/default_bsedict.rst", "w") as f:
-        lines = [
-            ".. ipython:: python",
-            "",
-            "    BSEDict = {",
-        ]
-
-        first = True
-        current_line = indent_str
-        for k, v in defaults.items():
-            entry = f'"{k}": {v}'
-            if not first:
-                entry = ", " + entry
-            first = False
-
-            # check if adding this entry would exceed line length
-            if len(current_line) + len(entry) > MAX_LINE_LENGTH:
-                lines.append(current_line.rstrip() + ",")
-                current_line = indent_str + entry.lstrip(", ")
-            else:
-                current_line += entry
+    lines = [
+        ".. ipython:: python",
+        "",
+        "    BSEDict = {",
+    ]
+
+    first = True
+    current_line = indent_str
+    for k, v in defaults.items():
+        entry = f'"{k}": {v}'
+        if not first:
+            entry = ", " + entry
+        first = False
+
+        # check if adding this entry would exceed line length
+        if len(current_line) + len(entry) > MAX_LINE_LENGTH:
+            lines.append(current_line.rstrip() + ",")
+            current_line = indent_str + entry.lstrip(", ")
+        else:
+            current_line += entry
+
+    if current_line.strip():
+        lines.append(current_line.rstrip())
+    lines.append("    }")
+
+    content = "\n".join(lines)
+    out_path = "_generated/default_bsedict.rst"
 
-        if current_line.strip():
-            lines.append(current_line.rstrip())
-        lines.append("    }")
+    if exists(out_path):
+        with open(out_path) as f:
+            if f.read() == content:
+                print(f"  No changes to {out_path}, skipping write.")
+                return
 
-        f.write("\n".join(lines))
+    with open(out_path, "w") as f:
+        print(f"  Writing default BSE settings to {out_path}...")
+        f.write(content)
 
 if __name__ == "__main__":
     generate_rst_bsedict()

docs/index.rst

@@ -23,17 +23,14 @@ Welcome to COSMIC!
     :alt: COSMIC logo
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
     :hidden:
 
     pages/about
     pages/install
     pages/reference_material
-    pages/examples
-    pages/runpop
-    pages/fixedpop
-    pages/multiprocessing
+    pages/tutorials
+    pages/api
     pages/cite
-    pages/developers
     _generated/whats_new
-    pages/api
+    pages/developers

docs/pages/reference_material.rst

@@ -14,7 +14,7 @@ Configuration and output
         .. toctree::
             :maxdepth: 1
 
-            inifile.rst
+            config_and_output/inifile.rst
 
         Instructions for creating configurations files and explanations of each option.
 
@@ -25,7 +25,7 @@ Configuration and output
         .. toctree::
             :maxdepth: 1
 
-            output_info.rst
+            config_and_output/output_info.rst
 
         Descriptions of the output files generated by COSMIC simulations.