Address admonition title accessibility issue (#3687)

* Converts admonition title elements from p tags to h2 tags
boto · May 11, 2023 · 22003b4 · 22003b4
1 parent eb2f02b
commit 22003b4
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 21 deletions.
diff --git a/docs/source/_static/css/custom.css b/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;
+}
diff --git a/docs/source/_static/js/custom.js b/docs/source/_static/js/custom.js
@@ -91,18 +91,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() {
@@ -121,18 +109,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.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -19,6 +19,12 @@
 import boto3.session
 from boto3.docs import generate_docs
 
+try:
+    from botocore.docs.translator import BotoHTML5Translator
+    CUSTOM_HTML_TRANSLATOR = BotoHTML5Translator
+except ImportError:
+    CUSTOM_HTML_TRANSLATOR = None
+
 
 session = boto3.session.Session(region_name='us-east-1')
 generate_docs(os.path.dirname(os.path.abspath(__file__)), session)
@@ -296,3 +302,9 @@
 #texinfo_show_urls = 'footnote'
 
 autoclass_content = 'both'
+
+
+def setup(app):
+    # Register our custom HTML translator.
+    if CUSTOM_HTML_TRANSLATOR:
+        app.set_translator("html", CUSTOM_HTML_TRANSLATOR)