Added furo theme to boto3 documentation. (boto#3631)

Update to furo for documentation theme.

boto3/docs/action.py

@@ -54,6 +54,9 @@ def document_actions(self, section):
         for action_name in sorted(resource_actions):
             # Create a new DocumentStructure for each action and add contents.
             action_doc = DocumentStructure(action_name, target='html')
+            breadcrumb_section = action_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Action / {action_name}')
             action_doc.add_title_section(action_name)
             action_section = action_doc.add_new_section(
                 action_name,

boto3/docs/base.py

@@ -26,6 +26,9 @@ def __init__(self, resource):
         self.represents_service_resource = (
             self._service_name == self._resource_name
         )
+        self._resource_class_name = self._resource_name
+        if self._resource_name == self._service_name:
+            self._resource_class_name = 'ServiceResource'
 
     @property
     def class_name(self):

boto3/docs/collection.py

@@ -43,6 +43,9 @@ def document_collections(self, section):
             collections_list.append(collection.name)
             # Create a new DocumentStructure for each collection and add contents.
             collection_doc = DocumentStructure(collection.name, target='html')
+            breadcrumb_section = collection_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Collection / {collection.name}')
             collection_doc.add_title_section(collection.name)
             collection_section = collection_doc.add_new_section(
                 collection.name,

boto3/docs/resource.py

@@ -56,7 +56,8 @@ def document_resource(self, section):
         self._add_waiters(section)
 
     def _add_title(self, section):
-        section.style.h2(self._resource_name)
+        title_section = section.add_new_section('title')
+        title_section.style.h2(self._resource_name)
 
     def _add_intro(self, section):
         identifier_names = []
@@ -157,6 +158,9 @@ def _add_identifiers(self, section):
             member_list.append(identifier.name)
             # Create a new DocumentStructure for each identifier and add contents.
             identifier_doc = DocumentStructure(identifier.name, target='html')
+            breadcrumb_section = identifier_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Identifier / {identifier.name}')
             identifier_doc.add_title_section(identifier.name)
             identifier_section = identifier_doc.add_new_section(
                 identifier.name,
@@ -209,6 +213,9 @@ def _add_attributes(self, section):
             attribute_list.append(attr_name)
             # Create a new DocumentStructure for each attribute and add contents.
             attribute_doc = DocumentStructure(attr_name, target='html')
+            breadcrumb_section = attribute_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Attribute / {attr_name}')
             attribute_doc.add_title_section(attr_name)
             attribute_section = attribute_doc.add_new_section(
                 attr_name,
@@ -253,6 +260,9 @@ def _add_references(self, section):
             reference_list.append(reference.name)
             # Create a new DocumentStructure for each reference and add contents.
             reference_doc = DocumentStructure(reference.name, target='html')
+            breadcrumb_section = reference_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Reference / {reference.name}')
             reference_doc.add_title_section(reference.name)
             reference_section = reference_doc.add_new_section(
                 reference.name,
@@ -335,7 +345,8 @@ def class_name(self):
         return f'{self._service_docs_name}.ServiceResource'
 
     def _add_title(self, section):
-        section.style.h2('Service Resource')
+        title_section = section.add_new_section('title')
+        title_section.style.h2('Service Resource')
 
     def _add_description(self, section):
         official_service_name = get_official_service_name(self._service_model)

boto3/docs/service.py

@@ -41,7 +41,6 @@ def __init__(self, service_name, session, root_docs_path):
             self._service_resource = self._boto3_session.resource(service_name)
         self.sections = [
             'title',
-            'table-of-contents',
             'client',
             'paginators',
             'waiters',
@@ -63,7 +62,6 @@ def document_service(self):
             self._service_name, section_names=self.sections, target='html'
         )
         self.title(doc_structure.get_section('title'))
-        self.table_of_contents(doc_structure.get_section('table-of-contents'))
 
         self.client_api(doc_structure.get_section('client'))
         self.paginator_api(doc_structure.get_section('paginators'))
@@ -111,6 +109,11 @@ def _document_service_resource(self, section):
         service_resource_doc = DocumentStructure(
             'service-resource', target='html'
         )
+        breadcrumb_section = service_resource_doc.add_new_section('breadcrumb')
+        breadcrumb_section.style.ref(
+            self._client.__class__.__name__, f'../../{self._service_name}'
+        )
+        breadcrumb_section.write(' / Resource / ServiceResource')
         ServiceResourceDocumenter(
             self._service_resource, self._session, self._root_docs_path
         ).document_resource(service_resource_doc)
@@ -158,6 +161,13 @@ def _document_resources(self, section):
             # Create a new DocumentStructure for each Resource and add contents.
             resource_name = resource.meta.resource_model.name.lower()
             resource_doc = DocumentStructure(resource_name, target='html')
+            breadcrumb_section = resource_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(
+                self._client.__class__.__name__, f'../../{self._service_name}'
+            )
+            breadcrumb_section.write(
+                f' / Resource / {resource.meta.resource_model.name}'
+            )
             ResourceDocumenter(
                 resource, self._session, self._root_docs_path
             ).document_resource(

boto3/docs/subresource.py

@@ -49,6 +49,9 @@ def document_sub_resources(self, section):
             sub_resource_doc = DocumentStructure(
                 sub_resource.name, target='html'
             )
+            breadcrumb_section = sub_resource_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Sub-Resource / {sub_resource.name}')
             sub_resource_doc.add_title_section(sub_resource.name)
             sub_resource_section = sub_resource_doc.add_new_section(
                 sub_resource.name,

boto3/docs/waiter.py

@@ -46,6 +46,9 @@ def document_resource_waiters(self, section):
             waiter_list.append(waiter.name)
             # Create a new DocumentStructure for each waiter and add contents.
             waiter_doc = DocumentStructure(waiter.name, target='html')
+            breadcrumb_section = waiter_doc.add_new_section('breadcrumb')
+            breadcrumb_section.style.ref(self._resource_class_name, 'index')
+            breadcrumb_section.write(f' / Waiter / {waiter.name}')
             waiter_doc.add_title_section(waiter.name)
             waiter_section = waiter_doc.add_new_section(
                 waiter.name,

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

docs/source/_static/css/custom.css

@@ -0,0 +1,33 @@
+/* Prevents two-dimensional scrolling and content loss. */
+h1, code, li {
+    overflow-wrap: break-word;
+}
+/* Provides padding to push down the "breadcrumb" navigation in nested pages. */
+.content{
+    padding: 1em 3em;
+}
+/* Improves spacing around custom sidebar section*/
+.sidebar-div{
+    margin: var(--sidebar-caption-space-above) 0 0 0;
+    padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
+}
+/* Custom sidebar heading text. Example: Feedback Section heading. */
+.sidebar-heading{
+    color: var(--color-sidebar-caption-text);
+    font-size: var(--font-size--normal);
+    font-weight: 700;
+}
+/* Improves text used in custom sidebar section. Example: Feedback section content.*/
+.sidebar-text{
+    color: var(--color-sidebar-caption-text);
+    font-size: var(--sidebar-item-font-size);
+    line-height: 1.4;
+}
+/* Removes empty space above the sidebar-tree (under "Feedback" section) */
+.sidebar-tree{
+    margin-top: 0px;
+}
+/* Adds padding around AWS Logo in the left sidebar. */
+.sidebar-logo{
+    padding: 20% 15%;
+}

docs/source/_static/js/custom.js

@@ -23,7 +23,7 @@ const nonResourceSubHeadings = [
 // Checks if an html doc name matches a service class name.
 function isValidServiceName(serviceClassName) {
 	const pageTitle = document.getElementsByTagName('h1')[0];
-	const newDocName = pageTitle.getElementsByTagName('a')[0].innerHTML;
+	const newDocName = pageTitle.innerText.replace('#', '');
 	return newDocName.toLowerCase() === serviceClassName;
 }
 // Checks if all elements of the split fragment are valid.
@@ -72,3 +72,29 @@ function isValidResource(name, serviceDocName) {
 		window.location.assign(newPath);
 	}
 }());
+// Given a service name, we apply the html classes which indicate a current page to the corresponsing list item.
+// Before: <li class="toctree-l2"><a class="reference internal" href="../../acm.html">ACM</a></li>
+// After: <li class="toctree-l2 current current-page"><a class="reference internal" href="../../acm.html">ACM</a></li>
+function makeServiceLinkCurrent(serviceName) {
+	const servicesSection = $("a:contains('Available Services')")[0].parentElement;
+	var linkElement = servicesSection.querySelectorAll(`a[href*="../${ serviceName }.html"]`);
+	if (linkElement.length === 0) {
+		linkElement = sideBarElement.querySelectorAll(`a[href="#"]`)[0];
+	} else {
+		linkElement = linkElement[0];
+	}
+	let linkParent = linkElement.parentElement;
+	linkParent.classList.add('current');
+	linkParent.classList.add('current-page');
+}
+// Expands the "Available Services" sub-menu in the side-bar when viewing
+// nested doc pages and highlights the corresponding service list item.
+const currentPagePath = window.location.pathname.split('/');
+const currentPagePathLength = currentPagePath.length;
+if (currentPagePath.includes('services')) {
+	document.getElementById('toctree-checkbox-11').checked = true;
+	// Example Nested Path: /reference/services/<service_name>/client/<operation_name>.html
+	const serviceNameIndex = currentPagePath.indexOf('services') + 1;
+	const serviceName = currentPagePath[serviceNameIndex];
+	makeServiceLinkCurrent(serviceName);
+}