From 94a660aa6fdb0159ed0264bd39b1a1e2e1d9bcf9 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sat, 18 Jan 2020 23:47:32 +0000 Subject: [PATCH] Use a responsive theme for docs With a pleasant ottanio background. --- doc/requirements.txt | 1 + doc/src/_static/psycopg.css | 101 +++++++++++++++++++++++++++++- doc/src/_templates/layout.html | 14 +++++ doc/src/_templates/searchbox.html | 6 ++ doc/src/conf.py | 19 ++++-- doc/src/index.rst | 1 + 6 files changed, 134 insertions(+), 8 deletions(-) create mode 100644 doc/src/_templates/layout.html create mode 100644 doc/src/_templates/searchbox.html diff --git a/doc/requirements.txt b/doc/requirements.txt index a24a0dcc..9449985d 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/src/_static/psycopg.css b/doc/src/_static/psycopg.css index f2fd1c1b..f7ff7560 100644 --- a/doc/src/_static/psycopg.css +++ b/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; + } +} diff --git a/doc/src/_templates/layout.html b/doc/src/_templates/layout.html new file mode 100644 index 00000000..46a2ee6b --- /dev/null +++ b/doc/src/_templates/layout.html @@ -0,0 +1,14 @@ +{# Override the sphinx theme for the docs to add analytics #} + +{%- extends "!layout.html" %} + +{%- block scripts %} + + + {{- super() }} +{%- endblock %} diff --git a/doc/src/_templates/searchbox.html b/doc/src/_templates/searchbox.html new file mode 100644 index 00000000..c51da22d --- /dev/null +++ b/doc/src/_templates/searchbox.html @@ -0,0 +1,6 @@ +{# Add a title over the search box #} + +{%- if pagename != "search" %} +

Quick search

+{%- include "!searchbox.html" %} +{%- endif %} diff --git a/doc/src/conf.py b/doc/src/conf.py index 8511e591..1b65c345 100644 --- a/doc/src/conf.py +++ b/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 # " v 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. diff --git a/doc/src/index.rst b/doc/src/index.rst index aa7fea5f..580d44aa 100644 --- a/doc/src/index.rst +++ b/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`