Addresses admonition accessibility issue

botocore/docs/bcdoc/style.py

@@ -125,6 +125,11 @@ def end_b(self):
         self.doc.do_translation = False
         self.end_bold()
 
+    def write_raw_h3(self, s):
+        self.start_raw_directive()
+        self.doc.write(f"<h3>{s}</h3>")
+        self.end_raw_directive()
+
     def bold(self, s):
         if s:
             self.start_bold()
@@ -186,35 +191,45 @@ def code(self, s):
             self.doc.write(s)
             self.end_code()
 
-    def start_note(self, attrs=None):
+    def start_raw_directive(self):
         self.new_paragraph()
-        self.doc.write('.. note::')
+        self.doc.write('.. raw:: html')
         self.indent()
         self.new_paragraph()
 
-    def end_note(self):
+    def end_raw_directive(self):
         self.dedent()
         self.new_paragraph()
 
+    def start_raw_admonition(self, type):
+        self.start_raw_directive()
+        self.doc.write(f'<div class="admonition {type}">')
+        self.new_line()
+        self.doc.write(f'<h3 class="admonition-title">{type.title()}</h3>')
+        self.end_raw_directive()
+
+    def end_raw_admonition(self):
+        self.start_raw_directive()
+        self.doc.write('</div>')
+        self.end_raw_directive()
+
+    def start_note(self, attrs=None):
+        self.start_raw_admonition('note')
+
+    def end_note(self):
+        self.end_raw_admonition()
+
     def start_important(self, attrs=None):
-        self.new_paragraph()
-        self.doc.write('.. warning::')
-        self.indent()
-        self.new_paragraph()
+        self.start_raw_admonition('warning')
 
     def end_important(self):
-        self.dedent()
-        self.new_paragraph()
+        self.end_raw_admonition()
 
     def start_danger(self, attrs=None):
-        self.new_paragraph()
-        self.doc.write('.. danger::')
-        self.indent()
-        self.new_paragraph()
+        self.start_raw_admonition('danger')
 
     def end_danger(self):
-        self.dedent()
-        self.new_paragraph()
+        self.end_raw_admonition()
 
     def start_a(self, attrs=None):
         # Write an empty space to guard against zero whitespace

botocore/docs/client.py

@@ -170,7 +170,7 @@ def _add_custom_method(self, section, method_name, method):
     def _add_method_exceptions_list(self, section, operation_model):
         error_section = section.add_new_section('exceptions')
         error_section.style.new_line()
-        error_section.style.bold('Exceptions')
+        error_section.style.write_raw_h3('Exceptions')
         error_section.style.new_line()
         for error in operation_model.error_shapes:
             class_name = (
@@ -334,7 +334,7 @@ def _add_top_level_documentation(self, section, shape):
 
     def _add_exception_catch_example(self, section, shape):
         section.style.new_line()
-        section.style.bold('Example')
+        section.style.write_raw_h3('Example')
         section.style.start_codeblock()
         section.write('try:')
         section.style.indent()
@@ -370,7 +370,7 @@ def _add_response_attr_description(self, section):
     def _add_response_example(self, section, shape):
         example_section = section.add_new_section('syntax')
         example_section.style.new_line()
-        example_section.style.bold('Syntax')
+        example_section.style.write_raw_h3('Syntax')
         example_section.style.new_paragraph()
         documenter = ResponseExampleDocumenter(
             service_name=self._service_name,
@@ -386,7 +386,7 @@ def _add_response_example(self, section, shape):
     def _add_response_params(self, section, shape):
         params_section = section.add_new_section('Structure')
         params_section.style.new_line()
-        params_section.style.bold('Structure')
+        params_section.style.write_raw_h3('Structure')
         params_section.style.new_paragraph()
         documenter = ResponseParamsDocumenter(
             service_name=self._service_name,

botocore/docs/method.py

@@ -220,7 +220,7 @@ def document_model_driven_method(
     # Add the example section.
     example_section = section.add_new_section('request-example')
     example_section.style.new_paragraph()
-    example_section.style.bold('Request Syntax')
+    example_section.style.write_raw_h3('Request Syntax')
 
     context = {
         'special_shape_types': {
@@ -292,7 +292,7 @@ def document_model_driven_method(
             'response-example'
         )
         return_example_section.style.new_line()
-        return_example_section.style.bold('Response Syntax')
+        return_example_section.style.write_raw_h3('Response Syntax')
         return_example_section.style.new_paragraph()
         ResponseExampleDocumenter(
             service_name=operation_model.service_model.service_name,
@@ -311,7 +311,7 @@ def document_model_driven_method(
             'description'
         )
         return_description_section.style.new_line()
-        return_description_section.style.bold('Response Structure')
+        return_description_section.style.write_raw_h3('Response Structure')
         return_description_section.style.new_paragraph()
         ResponseParamsDocumenter(
             service_name=operation_model.service_model.service_name,

botocore/docs/sharedexample.py

@@ -216,7 +216,7 @@ def document_shared_examples(
     """
     container_section = section.add_new_section('shared-examples')
     container_section.style.new_paragraph()
-    container_section.style.bold('Examples')
+    container_section.style.write_raw_h3('Examples')
     documenter = SharedExampleDocumenter()
     for example in shared_examples:
         documenter.document_shared_example(

docs/source/_static/css/custom.css

@@ -31,3 +31,32 @@ h1, code, li {
 .sidebar-logo{
     padding: 20% 15%;
 }
+
+/* Supporting style for replacing admonition titles from <p> to <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;
+}
+h3.admonition-title::before {
+    content: "";
+    position: absolute;
+    left: 0.5rem;
+    width: 1.5rem;
+    height: 1.5rem;
+}
+h3.admonition-title {
+    background-color: var(--color-admonition-title-background);
+}
+h3.admonition-title::before {
+    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.

tests/functional/docs/test_lex.py

@@ -20,10 +20,12 @@ def test_jsonheader_docs(self):
         docs = self.get_docstring_for_method('lex-runtime', 'post_content')
         self.assert_contains_lines_in_order(
             [
-                '**Request Syntax**',
+                '  .. raw:: html',
+                '    <h3>Request Syntax</h3>',
                 'sessionAttributes=%s,' % self.TYPE_STRING,
                 ':type sessionAttributes: JSON serializable',
-                '**Response Syntax**',
+                '  .. raw:: html',
+                '    <h3>Response Syntax</h3>',
                 '\'slots\': %s,' % self.TYPE_STRING,
                 '\'sessionAttributes\': %s' % self.TYPE_STRING,
                 '**slots** (JSON serializable)',

tests/unit/docs/bcdoc/test_style.py

@@ -128,19 +128,44 @@ def test_important(self):
         style = ReSTStyle(ReSTDocument())
         style.start_important()
         style.end_important()
-        self.assertEqual(style.doc.getvalue(), b'\n\n.. warning::\n\n  \n\n')
+        self.assertEqual(
+            style.doc.getvalue(),
+            (
+                b'\n\n.. raw:: html\n\n'
+                b'  <div class="admonition warning">\n'
+                b'  <h3 class="admonition-title">Warning</h3>\n\n'
+                b'\n\n.. raw:: html\n\n  </div>\n\n'
+            ),
+        )
 
     def test_note(self):
         style = ReSTStyle(ReSTDocument())
         style.start_note()
         style.end_note()
-        self.assertEqual(style.doc.getvalue(), b'\n\n.. note::\n\n  \n\n')
+        self.assertEqual(
+            style.doc.getvalue(),
+            (
+                b'\n\n.. raw:: html\n\n'
+                b'  <div class="admonition note">\n'
+                b'  <h3 class="admonition-title">Note</h3>\n\n'
+                b'\n\n.. raw:: html\n\n  </div>\n\n'
+            ),
+        )
 
     def test_danger(self):
         style = ReSTStyle(ReSTDocument())
         style.start_danger()
         style.end_danger()
-        self.assertEqual(style.doc.getvalue(), b'\n\n.. danger::\n\n  \n\n')
+        print(style.doc.getvalue())
+        self.assertEqual(
+            style.doc.getvalue(),
+            (
+                b'\n\n.. raw:: html\n\n'
+                b'  <div class="admonition danger">\n'
+                b'  <h3 class="admonition-title">Danger</h3>\n\n'
+                b'\n\n.. raw:: html\n\n  </div>\n\n'
+            ),
+        )
 
     def test_toctree_html(self):
         style = ReSTStyle(ReSTDocument())

tests/unit/docs/test_client.py

@@ -71,7 +71,8 @@ def test_document_client(self):
         self.assert_contains_lines_in_order(
             [
                 '.. py:method:: MyService.Client.sample_operation(**kwargs)',
-                '  **Request Syntax**',
+                '  .. raw:: html',
+                '    <h3>Request Syntax</h3>',
                 '  ::',
                 '    response = client.sample_operation(',
                 '        Biz=\'string\'',
@@ -80,15 +81,18 @@ def test_document_client(self):
                 '  :param Biz:',
                 '  :rtype: dict',
                 '  :returns:',
-                '    **Response Syntax**',
+                '    .. raw:: html',
+                '      <h3>Response Syntax</h3>',
                 '    ::',
                 '      {',
                 '          \'Biz\': \'string\'',
                 '      }',
-                '    **Response Structure**',
+                '    .. raw:: html',
+                '      <h3>Response Structure</h3>',
                 '    - *(dict) --*',
                 '      - **Biz** *(string) --*',
-                '**Exceptions**',
+                '  .. raw:: html',
+                '    <h3>Exceptions</h3>',
                 '*   :py:class:`MyService.Client.exceptions.SomeException`',
             ],
             self.get_nested_service_contents(
@@ -144,18 +148,22 @@ def test_modeled_exceptions(self):
         self.assert_contains_lines_in_order(
             [
                 '.. py:class:: MyService.Client.exceptions.SomeException',
-                '**Example**::',
+                '  .. raw:: html',
+                '    <h3>Example</h3>',
+                '::',
                 'except client.exceptions.SomeException as e:',
                 '.. py:attribute:: response',
-                '**Syntax**',
+                '    .. raw:: html',
+                '      <h3>Syntax</h3>',
                 '{',
                 "'Message': 'string',",
                 "'Error': {",
                 "'Code': 'string',",
                 "'Message': 'string'",
                 '}',
                 '}',
-                '**Structure**',
+                '    .. raw:: html',
+                '      <h3>Structure</h3>',
                 '- *(dict) --*',
                 '- **Message** *(string) --* ',
                 '- **Error** *(dict) --* ',