Merge pull request #823 from stan-dev/docs/mc-stan-theme

Update docs theming to match mc-stan.org

Author: WardBrian

docsrc/_static/css/custom.css

@@ -0,0 +1,31 @@
+html[data-theme="light"] {
+  --pst-color-background: #fefbf2;
+  --pst-color-primary: #3e8ebc;
+  --pst-color-secondary: #3e8ebc;
+  --pst-color-accent: #aed1e4;
+
+  --pst-color-text-base: #343a40;
+  --pst-color-heading: #222832;
+
+  header {
+    --pst-color-on-background: #052744;
+    --pst-color-text-muted: #f2e5bd;
+    --pst-color-text-base: #93b0f1;
+  }
+}
+
+html[data-theme="dark"] {
+  --pst-color-link: #aed1e4;
+  --pst-color-primary: #3e8ebc;
+  --pst-color-secondary: #3e8ebc;
+  --pst-color-accent: #aed1e4;
+
+  --pst-color-text-base: #faf1e4;
+
+  header {
+    --pst-color-on-background: #303030;
+    --pst-color-text-muted: #bdbdbd;
+    --pst-color-primary: #aed1e4;
+    --pst-color-text-base: #aed1e4;
+  }
+}

docsrc/_templates/layout.html

@@ -12,6 +12,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
 import subprocess
 import sys
@@ -136,7 +137,7 @@ def emit(self, record):
 
 # General information about the project.
 project = 'CmdStanPy'
-copyright = '2023, Stan Development Team'
+copyright = f'{datetime.date.today().year}, Stan Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -149,69 +150,26 @@ def emit(self, record):
 # The full version, including alpha/beta/rc tags.
 release = __version__
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build', '_templates']
 
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# Custom style
-html_style = 'css/project-template.css'
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'pydata_sphinx_theme'  # https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html
-# theme is customized via _templates/
+html_static_path = ["_static"]
+html_css_files = [
+    "css/custom.css",
+]
+html_favicon = "_static/images/logo_icon.png"
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-# html_theme_options = {}
+html_show_sphinx = False
 
 html_theme_options = {
-    "navbar_start": ["title"],
-    "page_sidebar_items": ["page-toc", "edit-this-page"],
     "icon_links": [
-        {
-            "name": "Twitter",
-            "url": "https://twitter.com/mcmc_stan",
-            "icon": "fab fa-twitter",
-        },
         {
             "name": "GitHub",
             "url": "https://github.com/stan-dev/cmdstanpy",
@@ -223,11 +181,29 @@ def emit(self, record):
             "icon": "fas fa-users",
         },
     ],
+    "logo": {
+        "text": "CmdStanPy v" + release if release else "CmdStanPy",
+        "alt_text": "CmdStanPy - Home",
+        "image_light": "_static/images/logo_tm.png",
+        "image_dark": "_static/images/logo_tm.png",
+    },
+    "navbar_align": "left",
+    "navbar_persistent": [],
+    "navbar_end": ["navbar-icon-links", "theme-switcher", "search-button"],
+    "footer_start": ["copyright"],
+    "footer_end": [],
+    "primary_sidebar_end": [],
+    "secondary_sidebar_items": {
+        "**": ["page-toc", "sourcelink", "edit-this-page"],
+        "index": [],
+    },
     "use_edit_page_button": True,
+    "default_mode": "light",
     "show_toc_level": 2,
+    "pygments_light_style": "tango",
+    "pygments_dark_style": "nord",
 }
 
-html_sidebars = {"index": ["search-field", 'logo']}
 
 html_context = {
     "github_user": "stan-dev",
@@ -405,7 +381,7 @@ def emit(self, record):
     "CmdStanVB": "~cmdstanpy.CmdStanVB",
     "CmdStanGQ": "~cmdstanpy.CmdStanGQ",
     "CmdStanLaplace": "~cmdstanpy.CmdStanLaplace",
-    "CmdStanPathfinder": "~cmdstanpy.CmdStanPathfinder"
+    "CmdStanPathfinder": "~cmdstanpy.CmdStanPathfinder",
 }
 
 nbsphinx_allow_errors = False

docsrc/_templates/logo.html

@@ -22,7 +22,7 @@ Python classes which provide methods to do analysis and manage the resulting
 set of model, data, and posterior estimates.
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 3
 
    installation
    users-guide

docsrc/_templates/title.html

@@ -52,8 +52,8 @@ test = [
     "polars>=1.8.2"
 ]
 docs = [
-    "sphinx>5,<6",
-    "pydata-sphinx-theme<0.9",
+    "sphinx<9",
+    "pydata-sphinx-theme<0.17",
     "nbsphinx",
     "ipython",
     "ipykernel<7",