Use a responsive theme for docs

With a pleasant ottanio background.

doc/requirements.txt

@@ -1,6 +1,7 @@
 # Packages only needed to build the docs
 Pygments>=2.2,<2.3
 Sphinx>=1.6,<=1.7
+sphinx-better-theme>=0.1.5,<0.2
 
 # 0.15.2 affected by https://sourceforge.net/p/docutils/bugs/353/
 # Can update to 0.16 after release (currently in rc) but must update Sphinx too

doc/src/_static/psycopg.css

@@ -1,5 +1,3 @@
-@import url("classic.css");
-
 blockquote {
     font-style: italic;
 }
@@ -37,3 +35,102 @@ dl.faq dt {
 table.data-types div.line-block {
     margin-bottom: 0;
 }
+
+
+/* better theme customisation */
+
+body {
+    background-color: #216464;
+}
+
+header, .related, .document, footer {
+    background-color: white;
+}
+
+header h1 {
+    font-size: 150%;
+    margin-bottom: 0;
+    padding: 0.5rem 10px 0.5rem 10px;
+}
+
+h1, h2, h3 {
+    font-weight: normal;
+}
+
+.body h1, .body h2, .body h3 {
+    color: #074848;
+}
+
+h1 {
+    font-size: 200%;
+}
+
+h2 {
+    font-size: 160%;
+}
+
+h3 {
+    font-size: 140%;
+}
+
+footer#pagefooter {
+    margin-bottom: 1rem;
+    font-size: 85%;
+    color: #444;
+}
+
+#rellinks, #breadcrumbs {
+    padding-right: 10px;
+    padding-left: 10px;
+}
+
+.sphinxsidebar {
+    padding-left: 10px;
+}
+
+.bodywrapper {
+    padding-right: 10px;
+}
+
+div.body h1, div.body h2, div.body h3 {
+    background-color: #f2f2f2;
+    border-bottom: 1px solid #d0d0d0;
+}
+
+div.body p.rubric {
+    border-bottom: 1px solid #d0d0d0;
+}
+
+body .sphinxsidebar .search {
+    margin-top: 0;
+}
+
+html pre {
+    background-color: #efc;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+a, a:visited {
+    color: #0b6868;
+}
+
+th {
+    background-color: #ede;
+}
+
+code.xref, a code {
+    font-weight: bold;
+}
+
+code.descname {
+    font-weight: bold;
+    font-size: 120%;
+}
+
+@media (max-width: 820px) {
+    body {
+        background-color: white;
+    }
+}

doc/src/_templates/layout.html

@@ -0,0 +1,14 @@
+{# Override the sphinx theme for the docs to add analytics #}
+
+{%- extends "!layout.html" %}
+
+{%- block scripts %}
+    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-19287248-2"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'UA-19287248-2');
+    </script>
+    {{- super() }}
+{%- endblock %}

doc/src/_templates/searchbox.html

@@ -0,0 +1,6 @@
+{# Add a title over the search box #}
+
+{%- if pagename != "search" %}
+<h3>Quick search</h3>
+{%- include "!searchbox.html" %}
+{%- endif %}

doc/src/conf.py

@@ -13,6 +13,7 @@
 
 import os
 import sys
+from better import better_theme_path
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -137,11 +138,11 @@ rst_epilog = """
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'classic'
+html_theme = 'better'
 
 # The stylesheet to use with HTML output: this will include the original one
 # adding a few classes.
-html_style = 'psycopg.css'
+# html_style = 'psycopg.css'
 
 # Hide the sphinx footer
 html_show_sphinx = False
@@ -149,17 +150,20 @@ html_show_sphinx = False
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    'linktotheme': False,
+    'cssfiles': ['_static/psycopg.css'],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+html_theme_path = [better_theme_path]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 # html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
+html_short_title = 'Home'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -184,7 +188,10 @@ html_static_path = ['_static']
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+# no need for the prev/next topic link using better theme: they are on top
+html_sidebars = {
+    '**': ['localtoc.html', 'searchbox.html'],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/src/index.rst

@@ -57,6 +57,7 @@ Psycopg 2 is both Unicode and Python 3 friendly.
     .. rubric:: Indices and tables
 
     * :ref:`genindex`
+    * :ref:`modindex`
     * :ref:`search`