Made recommend tweaks to MkDocs config to support ReadTheDocs

Author: tleonhardt

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.12"
+    python: "3"
 
 # Build documentation in the "docs/" directory with MkDocs
 mkdocs:

docs/api/index.md

@@ -1,15 +1,9 @@
----
-render_macros: true
----
-
 # API Reference
 
 These pages document the public API for `cmd2`. If a method, class, function, attribute, or constant is not documented here, consider it private and subject to change. There are many classes, methods, functions, and constants in the source code which do not begin with an underscore but are not documented here. When looking at the source code for this library, you cannot safely assume that because something doesn't start with an underscore, it is a public API.
 
 If a release of this library changes any of the items documented here, the version number will be incremented according to the [Semantic Version Specification](https://semver.org).
 
-This documentation is for `cmd2` version {{ release }}.
-
 ## Modules
 
 -   [cmd2.Cmd](./cmd.md) - functions and attributes of the main class in this library

docs/javascripts/readthedocs.js

@@ -0,0 +1,35 @@
+document.addEventListener("DOMContentLoaded", function (event) {
+  // Trigger Read the Docs' search addon instead of Material MkDocs default
+  document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+    const event = new CustomEvent("readthedocs-search-show");
+    document.dispatchEvent(event);
+  });
+});
+
+// Use CustomEvent to generate the version selector
+document.addEventListener("readthedocs-addons-data-ready", function (event) {
+  const config = event.detail.data();
+  const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${config.versions.active
+  .map(
+    (version) => `
+<li class="md-version__item">
+<a href="${version.urls.documentation}" class="md-version__link">
+    ${version.slug}
+</a>
+        </li>`
+  )
+  .join("\n")}
+</ul>
+</div>`;
+
+  document
+    .querySelector(".md-header__topic")
+    .insertAdjacentHTML("beforeend", versioning);
+});

docs/overrides/main.html

@@ -0,0 +1,3 @@
+{% extends "base.html" %} {% block site_meta %} {{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+{% endblock %}

docs/stylesheets/readthedocs.css

@@ -0,0 +1,11 @@
+:root {
+  /* Reduce Read the Docs' flyout font a little bit */
+  --readthedocs-flyout-font-size: 0.7rem;
+
+  /* Reduce Read the Docs' notification font a little bit */
+  --readthedocs-notification-font-size: 0.8rem;
+
+  /* This customization is not yet perfect because we can't change the `line-height` yet. */
+  /* See https://github.com/readthedocs/addons/issues/197 */
+  --readthedocs-search-font-size: 0.7rem;
+}

mkdocs.yml

@@ -2,7 +2,7 @@
 site_name: cmd2
 site_description: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python.
 site_dir: build/html
-site_url: https://cmd2.readthedocs.io/
+site_url: !ENV [READTHEDOCS_CANONICAL_URL, https://cmd2.readthedocs.io/] 
 
 # Repository
 repo_name: cmd2
@@ -16,6 +16,7 @@ copyright: Copyright © 2010-2024, cmd2 contributors.
 theme:
   name: material
   language: en
+  custom_dir: docs/overrides
   icon:
     repo: fontawesome/brands/github
     logo: material/home
@@ -96,7 +97,6 @@ extra:
       link: https://github.com/python-cmd2/cmd2
     - icon: simple/pypi
       link: https://pypi.org/project/cmd2/
-  release: "2.5"
 
 # Extensions
 # - These are carefully chosen to work with pandoc markdown support for whole document translation
@@ -209,3 +209,11 @@ nav:
       - api/plugin_external_test.md
   - Meta:
       - doc_conventions.md
+
+# Include extra CSS to make some style adjustments
+extra_css:
+  - stylesheets/readthedocs.css
+
+# Include extra JS to setup Read the Docs addons integrations
+extra_javascript:
+  - javascripts/readthedocs.js