Customize version selector menu

sphinx_versioned/__main__.py

@@ -61,6 +61,9 @@ def main(
     floating_badge: bool = typer.Option(
         False, "--floating-badge", "--badge", help="Turns the version selector menu into a floating badge."
     ),
+    menu_template: str = typer.Option(
+        None, "--template", help="Use version selector menu from template at the path."
+    ),
     quite: bool = typer.Option(
         True, help="Silent `sphinx`. Use `--no-quite` to get build output from `sphinx`."
     ),
@@ -122,6 +125,7 @@ def main(
 
     EventHandlers.RESET_INTERSPHINX_MAPPING = reset_intersphinx_mapping
     EventHandlers.FLYOUT_FLOATING_BADGE = floating_badge
+    log.info(f"template: {menu_template}")
 
     if reset_intersphinx_mapping:
         log.warning("Forcing --no-prebuild")
@@ -149,6 +153,7 @@ def main(
             "verbose": verbose,
             "loglevel": loglevel,
             "force_branches": force_branches,
+            "menu_template": menu_template,
         }
     )
 

sphinx_versioned/_templates/versions.html

@@ -1,12 +1,19 @@
+{% if menu_template %}
+{% extends menu_template %}
+{% endif %}
+{% block injected_code %}
 <div class="injected">
   <div class="rst-versions {{ 'rst-badge' if floating_badge }}" data-toggle="rst-versions" role="note"
     aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
+      {% block current_version %}
       <span class="fa fa-book">&nbsp;&nbsp;Other versions&nbsp;&nbsp;</span>
       v: {{ current_version }}
       <span class="fa fa-caret-down"></span>
+      {% endblock %}
     </span>
     <div class="rst-other-versions">
+      {% block tags %}
       {%- if versions.tags %}
       <dl>
         <dt>Tags</dt>
@@ -17,6 +24,8 @@
         {%- endfor %}
       </dl>
       {%- endif %}
+      {% endblock %}
+      {% block branches %}
       {%- if versions.branches %}
       <dl>
         <dt>Branches</dt>
@@ -27,6 +36,8 @@
         {%- endfor %}
       </dl>
       {%- endif %}
+      {% endblock %}
+      {% block project_info %}
       {%- if project_url %}
       <dl>
         <dt>Project home</dt>
@@ -35,6 +46,8 @@
         </dd>
       </dl>
       {%- endif %}
+      {% endblock %}
+      {% block searchbar %}
       <dl>
         <dt>Search</dt>
         <dd>
@@ -47,6 +60,8 @@
           </div>
         </dd>
       </dl>
+      {% endblock %}
     </div>
   </div>
-</div>
+</div>
+{% endblock %}

sphinx_versioned/build.py

@@ -87,6 +87,13 @@ def _handle_paths(self) -> None:
             log.error(f"conf.py does not exist at {self.local_conf}")
             raise FileNotFoundError(f"conf.py not found at {self.local_conf.parent}")
 
+        if self.menu_template:
+            self.menu_template = self.local_conf.parent.absolute() / '_templates' / self.menu_template
+            log.debug(f"Template path = {self.menu_template}")
+            assert self.menu_template.is_file()
+
+            EventHandlers.MENU_TEMPLATE = str(self.menu_template)
+
         log.success(f"located conf.py")
         return
 

sphinx_versioned/sphinx_.py

@@ -33,6 +33,7 @@ class EventHandlers(object):
     ASSETS_TO_COPY: set = set()
     RESET_INTERSPHINX_MAPPING: bool = False
     FLYOUT_FLOATING_BADGE: bool = False
+    MENU_TEMPLATE: str = None
     # Themes which do not require the additional `_rtd_versions.js` script file.
     _FLYOUT_NOSCRIPT_THEMES: list = [
         "sphinx_rtd_theme",
@@ -127,6 +128,7 @@ def html_page_context(cls, app, pagename, templatename, context, doctree) -> Non
         context["project_url"] = app.config.sv_project_url
         context["versions"] = cls.VERSIONS
         context["floating_badge"] = cls.FLYOUT_FLOATING_BADGE
+        context["menu_template"] = cls.MENU_TEMPLATE
 
         # Relative path to master_doc
         relpath = (pagename.count("/")) * "../"