From 3fea2ac05e84dfbac3bc168aec824d582caeacfa Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Sun, 18 Jun 2017 01:24:27 +0200 Subject: [PATCH] docs: switch to a fresher theme incidentally, fixes font size mismatches on firefox and chrome, at the same time. marvellous. --- docs/_templates/globaltoc.html | 10 ++++++++ docs/_templates/logo-text.html | 5 ++++ docs/borg_theme/css/borg.css | 40 +++++++++++++++++++++++++++--- docs/conf.py | 45 +++++++++++++++++----------------- requirements.d/docs.txt | 2 ++ 5 files changed, 76 insertions(+), 26 deletions(-) create mode 100644 docs/_templates/globaltoc.html create mode 100644 docs/_templates/logo-text.html create mode 100644 requirements.d/docs.txt diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html new file mode 100644 index 000000000..7841437c8 --- /dev/null +++ b/docs/_templates/globaltoc.html @@ -0,0 +1,10 @@ +
+
+ {% set toctree = toctree(maxdepth=3, collapse=True, includehidden=True) %} + {% if toctree %} + {{ toctree }} + {% else %} + {{ toc }} + {% endif %} +
+
diff --git a/docs/_templates/logo-text.html b/docs/_templates/logo-text.html new file mode 100644 index 000000000..dde5c9295 --- /dev/null +++ b/docs/_templates/logo-text.html @@ -0,0 +1,5 @@ + diff --git a/docs/borg_theme/css/borg.css b/docs/borg_theme/css/borg.css index 805e72e57..52a14eba3 100644 --- a/docs/borg_theme/css/borg.css +++ b/docs/borg_theme/css/borg.css @@ -39,12 +39,45 @@ dt code { font-weight: normal; } -.experimental, +/* bootstrap has a .container class which clashes with docutils' container class. */ +.docutils.container { + width: auto; + margin: 0; + padding: 0; +} + +/* the default (38px) produces a jumpy baseline in Firefox on Linux. */ +h1 { + font-size: 36px; +} + +.text-logo { + background-color: #000200; + color: #00dd00; +} + +.text-logo:hover, +.text-logo:active, +.text-logo:focus { + color: #5afe57; +} + +/* by default the top and bottom margins are unequal which looks a bit unbalanced. */ +.sidebar-block { + padding: 0; + margin: 14px 0 14px 0; +} + +#borg-documentation .external img { + width: 100%; +} + +.container.experimental, #debugging-facilities, #borg-recreate { /* don't change text dimensions */ - margin: 0 -40px; /* padding below + border width */ - padding: 0 20px; /* 20 px visual margin between edge of text and the border */ + margin: 0 -30px; /* padding below + border width */ + padding: 0 10px; /* 10 px visual margin between edge of text and the border */ /* fallback for browsers that don't have repeating-linear-gradient: thick, red lines */ border-left: 20px solid red; border-right: 20px solid red; @@ -98,7 +131,6 @@ p .literal span { cite { white-space: nowrap; color: black; /* slight contrast with #404040 of regular text */ - font-size: 75%; font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace; font-style: normal; diff --git a/docs/conf.py b/docs/conf.py index 4804bcffa..8f6b867c7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,8 +19,6 @@ sys.path.insert(0, os.path.abspath('../src')) from borg import __version__ as sw_version -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -51,7 +49,8 @@ copyright = '2010-2014 Jonas Borgström, 2015-2017 The Borg Collective (see AUTH # built documents. # # The short X.Y version. -version = sw_version.split('-')[0] +split_char = '+' if '+' in sw_version else '-' +version = sw_version.split(split_char)[0] # The full version, including alpha/beta/rc tags. release = version @@ -100,25 +99,21 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -#html_theme = '' -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - html_style = 'css/borg.css' -else: - html_context = { - 'css_files': [ - 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', - 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', - '_static/css/borg.css', - ], - } +import guzzle_sphinx_theme + +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + + +def setup(app): + app.add_stylesheet('css/borg.css') # 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 = { + 'project_nav_name': 'Borg %s' % version, +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = ['_themes'] @@ -132,7 +127,7 @@ else: # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/logo.png' +html_logo = '_static/logo.svg' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -156,9 +151,9 @@ html_use_smartypants = True # Custom sidebar templates, maps document names to template names. html_sidebars = { - 'index': ['sidebarlogo.html', 'sidebarusefullinks.html', 'searchbox.html'], - '**': ['sidebarlogo.html', 'relations.html', 'searchbox.html', 'localtoc.html', 'sidebarusefullinks.html'] + '**': ['logo-text.html', 'searchbox.html', 'globaltoc.html'], } + # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} @@ -248,7 +243,13 @@ man_pages = [ 1), ] -extensions = ['sphinx.ext.extlinks', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] +extensions = [ + 'sphinx.ext.extlinks', + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', +] extlinks = { 'issue': ('https://github.com/borgbackup/borg/issues/%s', '#'), diff --git a/requirements.d/docs.txt b/requirements.d/docs.txt new file mode 100644 index 000000000..b63e8185e --- /dev/null +++ b/requirements.d/docs.txt @@ -0,0 +1,2 @@ +sphinx +guzzle_sphinx_theme