[FIX] doc: new theme snags

* fix handling of no banner (and no default banner) on documents:
  - don't try to build a banner URL at the top of document
  - don't build a mini-banner in cards
* fix compatibility between custom HTML translator and domains creating
  new nodes (and their rendering): hook translator via
  app.add_translator so app.add_node can do the job correctly: with
  html_translator_class the application is not aware of the new HTML
  translator and add_node can't add the relevant rendering methods
* add translation for line_block and line (classes not used, point is
  just to have a div for each line so "newlines" are kept

doc/_extensions/odoo/__init__.py

@@ -1,13 +1,15 @@
 # -*- coding: utf-8 -*-
 
-from . import switcher
 from . import pygments_override
-import collections
+from . import switcher
+from . import translator
 
 import sphinx.environment
 import sphinx.builders.html
 from docutils import nodes
 def setup(app):
+    app.set_translator('html', translator.BootstrapTranslator)
+
     switcher.setup(app)
     app.add_config_value('odoo_cover_default', None, 'env')
     app.add_config_value('odoo_cover_external', {}, 'env')

doc/_extensions/odoo/layout.html

@@ -46,7 +46,7 @@
 {%- block header -%}
   <header class="{{ ' '.join(classes) }}">
     <figure class="card top">
-      <span class="card-img" style="background-image: url('{{ pathto('_static/' + meta['banner'], True) }}');"></span>
+      <span class="card-img" {% if meta['banner'] %}style="background-image: url('{{ pathto('_static/' + meta['banner'], True) }}');"{% endif %}></span>
     </figure>
   </header>
   <nav id="main_navbar" class="navbar {{ ' '.join(classes) }}">

doc/_extensions/odoo/translator.py

@@ -364,6 +364,18 @@ def depart_caption(self, node):
     def visit_legend(self, node): pass
     def depart_legend(self, node): pass
 
+    def visit_line(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='line'))
+        # ensure the line still takes the room it needs
+        if not len(node): self.body.append(u'<br />')
+    def depart_line(self, node):
+        self.body.append(u'</div>')
+
+    def visit_line_block(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='line-block'))
+    def depart_line_block(self, node):
+        self.body.append(u'</div>')
+
     def visit_table(self, node):
         self.body.append(self.starttag(node, 'table', CLASS='table'))
     def depart_table(self, node):
@@ -591,31 +603,39 @@ def visit_toctree(self, node):
 
             entries = [(title, ref)] if not toc else ((e[0], e[1]) for e in toc[0]['entries'])
             for subtitle, subref in entries:
+                baseuri = self.builder.get_target_uri(node['parent'])
+
                 if subref in env.metadata:
                     cover = env.metadata[subref].get('banner', conf.odoo_cover_default)
                 elif subref in conf.odoo_cover_external:
                     cover = conf.odoo_cover_external[subref]
                 else:
                     cover = conf.odoo_cover_default_external
-                banner = '_static/' + cover
-                base, ext = os.path.splitext(banner)
-                small = "{}.small{}".format(base, ext)
-                if os.path.isfile(urllib.url2pathname(small)):
-                    banner = small
-                baseuri = self.builder.get_target_uri(node['parent'])
+
+                if cover:
+                    banner = '_static/' + cover
+                    base, ext = os.path.splitext(banner)
+                    small = "{}.small{}".format(base, ext)
+                    if os.path.isfile(urllib.url2pathname(small)):
+                        banner = small
+                    style = u"background-image: url('{}')".format(
+                        util.relative_uri(baseuri, banner) or '#')
+                else:
+                    style = u''
+
                 self.body.append(u"""
                 <div class="col-sm-6 col-md-3">
                 <figure class="card">
                     <a href="{link}" class="card-img">
-                        <span style="background-image: url('{banner}')"></span>
+                        <span style="{style}"></span>
                         <figcaption>{title}</figcaption>
                     </a>
                 </figure>
                 </div>
                 """.format(
                     link=subref if util.url_re.match(subref) else util.relative_uri(
                         baseuri, self.builder.get_target_uri(subref)),
-                    banner=util.relative_uri(baseuri, banner) or '#',
+                    style=style,
                     title=subtitle if subtitle else util.nodes.clean_astext(env.titles[subref]),
                 ))
 

doc/conf.py

@@ -92,7 +92,6 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'odoo'
-html_translator_class = 'odoo.translator.BootstrapTranslator'
 
 odoo_cover_default = 'banners/installing_odoo.jpg'
 odoo_cover_external = {