diff --git a/conf.py b/conf.py
index 7b5123524..a2396f7cb 100644
--- a/conf.py
+++ b/conf.py
@@ -164,9 +164,8 @@ html_favicon = os.path.join(html_theme_path[0], html_theme, 'static', 'img', 'fa
 html_static_path = ['static']
 html_add_permalinks = '¶'  # Sphinx < 3.5
 html_permalinks = True  # Sphinx >= 3.5
-# Additional css & js files:
-# Empty because the js & css files are specified in the extensions/theme
-# or specified for a given page only through the custom-js & custom-css metadata directives
+# Additional JS & CSS files that can be imported with the 'custom-js' and 'custom-css' metadata.
+# Lists are empty because the files are specified in extensions/themes.
 html_js_files = []
 html_css_files = []
 
diff --git a/extensions/odoo_theme/layout.html b/extensions/odoo_theme/layout.html
index 20d38f0bf..f0ee34846 100644
--- a/extensions/odoo_theme/layout.html
+++ b/extensions/odoo_theme/layout.html
@@ -3,7 +3,7 @@
 
 {% block css %}
     {{ super() }}
-    {% if 'custom-css' in meta %}{# Allow custom css style import for specific pages #}
+    {% if 'custom-css' in meta %} {# Allow custom css style import for specific pages #}
         {% set css_files = meta['custom-css'].split(',') %}
         {% for css_file in css_files %}
             {% set link = '_static/css/' + css_file %}
@@ -13,7 +13,7 @@
 {% endblock %}
 
 {% block scripts %}
-    {% if 'custom-js' in meta %}{# Allow custom js import for specific pages #}
+    {% if 'custom-js' in meta %} {# Allow custom js import for specific pages #}
         {# Before the custom files using React & Immutable (accounting mementos) #}
         <script src="https://cdnjs.cloudflare.com/ajax/libs/immutable/3.8.2/immutable.min.js"
             integrity="sha512-myCdDiGJRYrvRb/VuJ67ljifYTJdc1jdEvL4c4ftX9o3N6EAnmD83c/7l2/91RCINZ7c8w21tiXDT7RDFjdc3g=="
@@ -58,7 +58,7 @@
             {% include "layout_templates/menu.html" %}
         </nav>
     </noscript>
-    {# shown when js has properly set all the classes on the toc elements #}
+    {# Shown when the JS has properly set all the classes on the TOC elements #}
     <nav id="o_main_toctree" class="o_side_nav border-end" hidden>
         {% include "layout_templates/menu.html" %}
     </nav>
@@ -101,11 +101,14 @@
                 {% include "layout_templates/homepage.html" %}
             {% else %}
                 <article id="o_content" class="doc-body">
-                    <div role="main">{# Beacon used by the Sphinx search to know where to look for a string #}
+                    <div role="main"> {# Beacon used by the Sphinx search to know where to look for a string #}
                         {% block body %} {% endblock %}
                     </div>
                     {% if github_link and pagename != 'search' %}
-                        <a href="{{ github_link(mode='edit') }}" class="o_git_link d-none d-lg-inline-block"><i class="i-edit"></i> Edit on GitHub</a>
+                        <a href="{{ github_link(mode='edit') }}"
+                           class="o_git_link d-none d-lg-inline-block">
+                            <i class="i-edit"></i> Edit on GitHub
+                        </a>
                     {% endif %}
                 </article>
             {% endif %}
diff --git a/extensions/odoo_theme/translator.py b/extensions/odoo_theme/translator.py
index 99f85d920..4d5cc4ce7 100644
--- a/extensions/odoo_theme/translator.py
+++ b/extensions/odoo_theme/translator.py
@@ -93,7 +93,7 @@ class BootstrapTranslator(HTML5Translator):
         self.body.append(u'[UNKNOWN NODE {}]'.format(node.__class__.__name__))
         raise nodes.SkipNode
 
-    # VFE NOTE: seems that when we remove/comment this, we get the titles 5 timesin the global toc :D
+    # NOTE: seems that when we remove/comment this, we get the titles 5 times in the global toc
     def visit_document(self, node):
         self.first_title = True
     def depart_document(self, node):