Addresses admonition accessibility issue

docs/source/_static/css/custom.css

@@ -31,3 +31,29 @@ h1, code, li {
 .sidebar-logo{
     padding: 20% 15%;
 }
+
+/* Apply furo styled admonition titles for <h3>. */
+h3.admonition-title {
+  position: relative;
+  margin: 0 -0.5rem 0.5rem;
+  padding-left: 2.5rem;
+  padding-right: .5rem;
+  padding-top: .4rem;
+  padding-bottom: .4rem;
+  font-weight: 700;
+  font-size: 1.5em;
+  line-height: 1.25;
+  border-radius: unset;
+  background-color: var(--color-admonition-title-background);
+}
+/* Apply furo styled admonition icons before <h3>. */
+h3.admonition-title::before {
+    content: "";
+    position: absolute;
+    left: 0.5rem;
+    width: 1.5rem;
+    height: 1.5rem;
+    background-color: var(--color-admonition-title);
+    mask-image: var(--icon-admonition-default);
+    mask-repeat: no-repeat;
+}

docs/source/_static/js/custom.js

@@ -82,18 +82,6 @@ function makeServiceLinkCurrent(serviceName) {
 }
 const currentPagePath = window.location.pathname.split('/');
 const codeBlockSelector = 'div.highlight pre';
-const boldTextSelector = 'strong';
-const boldElements = document.querySelectorAll(boldTextSelector);
-const headings = [
-	'Example',
-	'Examples',
-	'Exceptions',
-	'Request Syntax',
-	'Response Structure',
-	'Response Syntax',
-	'Structure',
-	'Syntax'
-];
 // Expands the "Available Services" sub-menu in the side-bar when viewing
 // nested doc pages and highlights the corresponding service list item.
 function expandSubMenu() {
@@ -112,18 +100,9 @@ function makeCodeBlocksScrollable() {
 		codeCell.tabIndex = 0;
 	});
 }
-// Converts implicit bold headings into actual headings with h3 tags.
-function convertImplicitHeadings() {
-	boldElements.forEach(boldElement => {
-		if (headings.includes(boldElement.innerHTML)) {
-			boldElement.parentElement.outerHTML = `<h3>${ boldElement.innerHTML }</h3>`;
-		}
-	});
-}
 // Functions to run after the DOM loads.
 function runAfterDOMLoads() {
 	expandSubMenu();
-	convertImplicitHeadings();
 	makeCodeBlocksScrollable();
 }
 // Run a function after the DOM loads.

docs/source/conf.py

@@ -14,6 +14,8 @@
 import datetime, sys, os
 from botocore.session import get_session
 from botocore.docs import generate_docs
+from sphinx.locale import admonitionlabels
+from sphinx.writers.html5 import HTML5Translator as SphinxHTML5Translator
 
 generate_docs(os.path.dirname(os.path.abspath(__file__)), get_session())
 
@@ -283,3 +285,53 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+class HTML5Translator(SphinxHTML5Translator):
+    """
+    This is our custom HTML5Translator which extends the one provided by Sphinx.
+    """
+    STRONG_TO_H3_HEADINGS = [
+        'Example',
+        'Examples',
+        'Exceptions',
+        'Request Syntax',
+        'Response Structure',
+        'Response Syntax',
+        'Structure',
+        'Syntax'
+    ]
+
+    def visit_admonition(self, node, name=''):
+        """Uses the h3 tag for admonition titles instead of the p tag"""
+        self.body.append(self.starttag(
+            node, 'div', CLASS=('admonition ' + name)))
+        if name:
+            title = (
+                f"<h3 class='admonition-title'>"
+                f"{admonitionlabels[name]}</h3>"
+            )
+            self.body.append(title)
+
+    def visit_strong(self, node):
+        """
+        Opens the h3 tag for a specific set of words/phrases and opens the
+        strong tag for all others.
+        """
+        if len(node) > 0 and node[0] in self.STRONG_TO_H3_HEADINGS:
+            self.body.append(self.starttag(node, 'h3', ''))
+        else:
+            self.body.append(self.starttag(node, 'strong', ''))
+
+    def depart_strong(self, node):
+        """
+        Closes the h3 tag for a specific set of words/phrases and closes the
+        strong tag for all others.
+        """
+        if node[0] in self.STRONG_TO_H3_HEADINGS:
+            self.body.append('</h3>')
+        else:
+            self.body.append('</strong>')
+
+def setup(app):
+    # Register our custom HTML translator.
+    app.set_translator('html', HTML5Translator)