Merge pull request #2694 from enkore/docs/themefix

switch docs theme

docs/_templates/globaltoc.html

@@ -0,0 +1,10 @@
+<div class="sidebar-block">
+  <div class="sidebar-toc">
+    {% set toctree = toctree(maxdepth=3, collapse=True, includehidden=True) %}
+    {% if toctree %}
+      {{ toctree }}
+    {% else %}
+      {{ toc }}
+    {% endif %}
+  </div>
+</div>

docs/_templates/logo-text.html

@@ -0,0 +1,5 @@
+<a href="{{ homepage() }}" class="text-logo">
+  <img src='{{ pathto('_static/logo.svg', 1) }}' width='100%'>
+
+  {{ theme_project_nav_name or shorttitle }}
+</a>

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 24px 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;

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', '#'),

docs/development.rst

@@ -237,9 +237,10 @@ Building the docs with Sphinx
 
 The documentation (in reStructuredText format, .rst) is in docs/.
 
-To build the html version of it, you need to have sphinx installed::
+To build the html version of it, you need to have Sphinx installed
+(in your Borg virtualenv with Python 3)::
 
-  pip3 install sphinx sphinx_rtd_theme  # important: this will install sphinx with Python 3
+  pip install -r requirements.d/docs.txt
 
 Now run::
 
@@ -248,7 +249,7 @@ Now run::
 
 Then point a web browser at docs/_build/html/index.html.
 
-The website is updated automatically through Github web hooks on the
+The website is updated automatically by ReadTheDocs through GitHub web hooks on the
 main repository.
 
 Using Vagrant

docs/installation.rst

@@ -173,20 +173,20 @@ Features & platforms
 
 Besides regular file and directory structures, |project_name| can preserve
 
-    * Symlinks (stored as symlink, the symlink is not followed)
-    * Special files:
-
-        * Character and block device files (restored via mknod)
-        * FIFOs ("named pipes")
-        * Special file *contents* can be backed up in ``--read-special`` mode.
-          By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
-    * Hardlinked regular files, devices, FIFOs (considering all items in the same archive)
-    * Timestamps in nanosecond precision: mtime, atime, ctime
-    * Permissions:
-
-        * IDs of owning user and owning group
-        * Names of owning user and owning group (if the IDs can be resolved)
-        * Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
+* Symlinks (stored as symlink, the symlink is not followed)
+* Special files:
+
+  * Character and block device files (restored via mknod)
+  * FIFOs ("named pipes")
+  * Special file *contents* can be backed up in ``--read-special`` mode.
+    By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
+* Hardlinked regular files, devices, FIFOs (considering all items in the same archive)
+* Timestamps in nanosecond precision: mtime, atime, ctime
+* Permissions:
+
+  * IDs of owning user and owning group
+  * Names of owning user and owning group (if the IDs can be resolved)
+  * Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
 
 On some platforms additional features are supported:
 

requirements.d/docs.txt

@@ -0,0 +1,2 @@
+sphinx
+guzzle_sphinx_theme