docs: a hack (to be tested) to include my layout.html from RTD

Author: wojdyr

doc/conf.py

@@ -12,9 +12,13 @@
 exclude_patterns = ['html', 'latex']
 if not os.getenv('BUILD_WEBSITE'):
     exclude_patterns += ['index.rst', 'screens.rst']
+
 if os.getenv('READTHEDOCS'):
     # RTD works better with index.html
     html_additional_pages = { 'index': '_build/html/fityk-manual.html' }
+    # RTD has own layout.html. This hack is needed to use all layout.html files.
+    template_bridge = "fityk_ext.MyTemplateLoader"
+
 templates_path = ['.']
 source_suffix = '.rst'
 source_encoding = 'utf-8'

doc/fityk_ext.py

@@ -42,3 +42,21 @@ def setup(app):
     app.add_lexer('fityk', FitykLexer());
     app.connect('doctree-read', doctree_read)
 
+
+
+# this is hack is needed to use our layout.html on ReadTheDocs
+from sphinx.jinja2glue import BuiltinTemplateLoader
+class MyTemplateLoader(BuiltinTemplateLoader):
+    def get_source(self, environment, template):
+        print "(MyTemplateLoader.get_source) searching for",  template
+        # If template name in Jinja's "extends" is prepended with "!"
+        # Sphinx skips project's template paths.
+        # In BuiltinTemplateLoader self.templatepathlen is used to remove
+        # project's template paths and leave only Sphinx's paths.
+        # This hack should leave the last path, so "!layout.html" will find
+        # the template from Fityk. To avoid recursion, Fityk template
+        # is not using "!".
+        self.templatepathlen -= 1
+        return BuiltinTemplateLoader.get_source(self, environment, template)
+        self.templatepathlen += 1
+

doc/layout.html

@@ -1,4 +1,7 @@
-{% extends "!layout.html" %}
+{% extends "sphinxdoc/layout.html" %}
+{# "!" (which is handled by sphinx BuiltinTemplateLoader is not used here,
+   to enable nesting in ReadTheDocs build.
+#}
 
 {% set reldelim1 = ' ' %}
 {% set reldelim2 = '   ' %}