Merge pull request #2639 from enkore/docs/experimental

docs: highlight experimental features in online docs

docs/borg_theme/css/borg.css

@@ -38,3 +38,17 @@ dt code {
 #internals .toctree-wrapper > ul > li > ul {
     font-weight: normal;
 }
+
+.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 */
+    /* fallback for browsers that don't have repeating-linear-gradient: thick, red lines */
+    border-left: 20px solid red;
+    border-right: 20px solid red;
+    /* fancy red-orange stripes */
+    border-image: repeating-linear-gradient(
+            -45deg,red 0,red 10px,#ffa800 10px,#ffa800 20px,red 20px) 0 20 repeat;
+}

docs/conf.py

@@ -74,6 +74,10 @@
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
 
+# The Borg docs contain no or very little Python docs.
+# Thus, the primary domain is rst.
+primary_domain = 'rst'
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 

docs/usage/general.rst

@@ -5,6 +5,13 @@ Borg consists of a number of commands. Each command accepts
 a number of arguments and options and interprets various environment variables.
 The following sections will describe each command in detail.
 
+.. container:: experimental
+
+   Experimental features are marked with red-orange stripes on the sides, like this paragraph.
+
+   Experimental features are not stable, which means that they may be changed in incompatible
+   ways or even removed entirely without prior notice in following releases.
+
 .. include:: ../usage_general.rst.inc
 
 In case you are interested in more details (like formulas), please see