docs: prettify

bundlewrap · Sep 28, 2017 · 1723966 · 1723966
1 parent edc79e6
commit 1723966
Show file tree

Hide file tree

Showing 33 changed files with 299 additions and 230 deletions.
diff --git a/docs/content/bundlewrap.css b/docs/content/bundlewrap.css
@@ -1,9 +1,15 @@
 @import url('https://fonts.googleapis.com/css?family=Maven+Pro');
 @import url('https://fonts.googleapis.com/css?family=Roboto:400,400i,700');
-body {
+@import url('https://fonts.googleapis.com/css?family=Source+Code+Pro:400,700');
+body, h1, h2, h3, h4, h5, h6 {
 	background: white;
 	font-family: Roboto, Helvetica, sans-serif;
 }
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	margin-bottom: 20px;
+}
+hr { border-top: 1px solid #f0f0f0; }
 .navbar {
 	background: black;
 }
@@ -16,3 +22,33 @@ body {
 .bs-sidebar .nav > li > a {
 	color: black;
 }
+.terminal {
+	background-color: black;
+	border-radius: 5px;
+	color: #d7d7d7;
+	font-family: source-code-pro, monospace;
+	font-size: 12px;
+	line-height: 140%;
+	margin-bottom: 32px;
+	margin-top: 32px;
+	overflow: scroll;
+	padding: 10px;
+	padding-left: 15px;
+	white-space: pre;
+}
+.btn-blue {
+    background-color: #1a8acc;
+    border: 1px solid white;
+    color: #f0f0f0;
+}
+.btn-blue:hover {
+	color: white;
+}
+.btn-blueoutline {
+    background-color: white;
+    border: 1px solid #1a8acc;
+    color: #1a8acc;
+}
+.btn-blueoutline:hover {
+	color: black;
+}
diff --git a/docs/content/guide/migrate_12.md b/docs/content/guide/migrate_12.md
@@ -26,7 +26,7 @@ The merging behavior for node and group metadata has changed. Instead of a simpl
 
 ## Metadata processors and item generators
 
-These two advanced features have been replaced by a single new mechanism: [metadata.py](../repo/bundles.md#metadatapy) You will need to rethink and rewrite them.
+These two advanced features have been replaced by a single new mechanism: [metadata.py](../repo/metadata.py.md) You will need to rethink and rewrite them.
 
 BundleWrap 1.6.0 will print warnings for every group that uses metadata processors and any item generators when running `bw test`.
 

diff --git a/docs/content/guide/migrate_23.md b/docs/content/guide/migrate_23.md
@@ -16,7 +16,7 @@ You will have to add `@metadata_processor` to each metadata processor function.
 
 The accepted return values of metadata processors have changed as well. Metadata processors now always have to return a tuple with the first element being a dictionary of metadata and the remaining elements made up of various options to tell BundleWrap what to do with the dictionary. In most cases, you will want to return the `DONE` options as in the example above. There is no need to import options, they're always available.
 
-When you previously returned `metadata, False` from a metadata processor, you will now have to return `metadata, RUN_ME_AGAIN`. For a more detailed description of the available options, see [the documentation](../repo/bundles.md#metadatapy).
+When you previously returned `metadata, False` from a metadata processor, you will now have to return `metadata, RUN_ME_AGAIN`. For a more detailed description of the available options, see [the documentation](../repo/metadata.py.md).
 
 <br>
 

diff --git a/docs/content/guide/quickstart.md b/docs/content/guide/quickstart.md
@@ -57,7 +57,7 @@ Instead of a node name ("node-1" in this case) you can also use a group name (su
 Create a bundle
 ---------------
 
-BundleWrap stores node configuration in [bundles](../repo/bundles.md). A bundle is a collection of *items* such as files, system packages or users. To create your first bundle, type:
+BundleWrap stores node configuration in bundles. A bundle is a collection of *items* such as files, system packages or users. To create your first bundle, type:
 
 <pre><code class="nohighlight">bw repo bundle create mybundle</code></pre>
 
@@ -135,7 +135,7 @@ Here are some suggestions on what to do next:
 * set up [SSH multiplexing](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) for significantly better performance
 * take a moment to think about what groups and bundles you will create
 * read up on how a [BundleWrap repository](../repo/layout.md) is laid out
-* ...especially what [types of items](../repo/bundles.md#item-types) you can add to your bundles
+* ...especially what [types of items](../repo/items.py.md#item-types) you can add to your bundles
 * familiarize yourself with [the Mako template language](http://www.makotemplates.org/)
 * explore the [command line interface](cli.md)
 * follow [@bundlewrap](https://twitter.com/bundlewrap) on Twitter

diff --git a/docs/content/index.md b/docs/content/index.md
@@ -1,40 +1,33 @@
 <style>.bs-sidebar { display: none; }</style>
-
-BundleWrap documentation
-========================
-
-Check out the [quickstart tutorial](guide/quickstart.md) to get started.
+<script>
+	$("div.col-md-3").remove();
+	$("div.col-md-9").attr("class", "col-md-12");
+</script>
+<h1 class="text-center">BundleWrap documentation</h1>
+
+<div class="text-center well" style="line-height: 75px;">
+	<a class="btn btn-lg btn-blue" href="/guide/quickstart">I want to learn BundleWrap!</a>
+	&nbsp;
+	<a class="btn btn-lg btn-blueoutline" href="/misc/deciding">Should I use BundleWrap?</a>
+</div>
 
 If you run into a problem that is not answered in these docs, please
 find us on [IRC](irc://chat.freenode.net/bundlewrap) or [Twitter](https://twitter.com/bundlewrap). We’re happy to help!
 
-<br>
-
-Is BundleWrap the right tool for you?
--------------------------------------
-
-We think you will enjoy BundleWrap a lot if you:
-
--   know some Python
--   like to write your configuration from scratch and control every bit
-    of it
--   have lots of unique nodes
--   are trying to get a lot of existing systems under management
--   are NOT trying to handle a massive amount of nodes (let’s say more
-    than 1000)
--   like to start small
--   don’t want yet more stuff to run on your nodes (or mess with
-    appliances as little as possible)
--   prefer a simple tool to a fancy one
--   want as much as possible in git/hg/bzr
--   have strongly segmented internal networks
-
-You might be better served with a different config management system if
-you:
-
--   are already using a config management system and don’t have any
-    major issues
--   hate Python and/or JSON
--   like to use community-maintained configuration templates
--   need unattended bootstrapping of nodes
--   don’t trust your coworkers
+Should you already know your way around, just click on the part of your repo that you need help with:
+
+<div class="terminal">bundles/
+    mybundle/
+        <a href="/repo/items.py">items.py</a>
+        <a href="/repo/metadata.py">metadata.py</a>
+        files/
+            <a href="/guide/item_file_templates">template</a>
+<a href="/items/file/#source">data/</a>
+<a href="/repo/hooks">hooks/</a>
+<a href="/guide/dev_item">items/</a>
+<a href="/guide/secrets">.secrets.cfg</a>
+<a href="/repo/groups.py">groups.py</a>
+<a href="/repo/nodes.py">nodes.py</a>
+<a href="/repo/plugins">plugins.json</a>
+<a href="/repo/requirements.txt">requirements.txt</a>
+</div>
diff --git a/docs/content/items/action.md b/docs/content/items/action.md
@@ -10,43 +10,43 @@ Actions will be run on every `bw apply`. They differ from regular items in that
         },
     }
 
-<br>
+<br><br>
 
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## command
 
 The only required attribute. This is the command that will be run on the node with root privileges.
 
-<br>
+<hr>
 
 ## data_stdin
 
 You can pipe data directly to the command running on the node. To do so, use this attribute. If it's a string or unicode object, it will always be encoded as UTF-8. Alternatively, you can use raw bytes.
 
-<br>
+<hr>
 
 ## expected_return_code
 
 Defaults to `0`. If the return code of your command is anything else, the action is considered failed. You can also set this to `None` and any return code will be accepted.
 
-<br>
+<hr>
 
 ## expected_stdout
 
 If this is given, the stdout output of the command must match the given string or the action is considered failed.
 
-<br>
+<hr>
 
 ## expected_stderr
 
 Same as `expected_stdout`, but with stderr.
 
-<br>
+<hr>
 
 ## interactive
 

diff --git a/docs/content/items/directory.md b/docs/content/items/directory.md
@@ -8,29 +8,31 @@
         },
     }
 
+<br><br>
+
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## group
 
 Name of the group this directory belongs to. Defaults to `'root'`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## mode
 
 Directory mode as returned by `stat -c %a <directory>`. Defaults to `755`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## owner
 
 Username of the directory's owner. Defaults to `'root'`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## purge
 

diff --git a/docs/content/items/file.md b/docs/content/items/file.md
@@ -13,19 +13,19 @@ Manage regular files.
         },
     }
 
-<br>
+<br><br>
 
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## content
 
 May be used instead of `source` to provide file content without a template file.
 
-<br>
+<hr>
 
 ## content_type
 
@@ -41,51 +41,51 @@ How the file pointed to by `source` or the string given to `content` should be i
 <tr><td><code>text</code> (default)</td><td>like <code>binary</code>, but will be diffed in interactive mode</td></tr>
 </table>
 
-<br>
+<hr>
 
 ## context
 
 Only used with Mako and Jinja2 templates. The values of this dictionary will be available from within the template as variables named after the respective keys.
 
-<br>
+<hr>
 
 ## delete
 
 When set to `True`, the path of this file will be removed. It doesn't matter if there is not a file but a directory or something else at this path. When using `delete`, no other attributes are allowed.
 
-<br>
+<hr>
 
 ## encoding
 
 Encoding of the target file. Note that this applies to the remote file only, your template is still conveniently written in UTF-8 and will be converted by BundleWrap. Defaults to "utf-8". Other possible values (e.g. "latin-1") can be found [here](http://docs.python.org/2/library/codecs.html#standard-encodings).
 
-<br>
+<hr>
 
 ## group
 
 Name of the group this file belongs to. Defaults to `'root'`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## mode
 
 File mode as returned by `stat -c %a <file>`. Defaults to `644`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## owner
 
 Username of the file's owner. Defaults to `'root'`. Set to `None` if you don't want BundleWrap to change whatever is set on the node.
 
-<br>
+<hr>
 
 ## source
 
 File name of the file template. If this says `my_template`, BundleWrap will look in `data/my_bundle/files/my_template` and then `bundles/my_bundle/files/my_template`. Most of the time, you will want to put config templates into the latter directory. The `data/` subdirectory is meant for files that are very specific to your infrastructure (e.g. DNS zone files). This separation allows you to write your bundles in a generic way so that they could be open-sourced and shared with other people. Defaults to the filename of this item (e.g. `foo.conf` when this item is `/etc/foo.conf`).
 
 See also: [Writing file templates](../guide/item_file_templates.md)
 
-<br>
+<hr>
 
 ## verify_with
 

diff --git a/docs/content/items/group.md b/docs/content/items/group.md
@@ -8,19 +8,19 @@ Manages system groups. Group members are managed through the [user item](user.md
         },
     }
 
-<br>
+<br><br>
 
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## delete
 
 When set to `True`, this group will be removed from the system. When using `delete`, no other attributes are allowed.
 
-<br>
+<hr>
 
 ## gid
 

diff --git a/docs/content/items/pkg_apt.md b/docs/content/items/pkg_apt.md
@@ -16,22 +16,26 @@ Handles packages installed by `apt-get` on Debian-based systems.
         },
     }
 
-<br>
+<br><br>
 
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## installed
 
 `True` when the package is expected to be present on the system; `False` if it should be purged.
 
+<hr>
+
 ## when\_creating
 
 These attributes are only enforced during the creation of the item on the node (in this case this means when a package is installed). They are ignored in subsequent runs of `bw apply`.
 
+<hr>
+
 ### start\_service
 
 By default, daemons will be auto-started on systems like Debian or Ubuntu. This happens right after the package has been installed. You might want to set `start_service` to `False` to avoid this. This might be necessary if BundleWrap must place some more config files on the node before a daemon can actually be started.
diff --git a/docs/content/items/pkg_dnf.md b/docs/content/items/pkg_dnf.md
@@ -11,13 +11,13 @@ Handles packages installed by `dnf` on RPM-based systems.
         },
     }
 
-<br>
+<br><br>
 
 # Attribute reference
 
-See also: [The list of generic builtin item attributes](../repo/bundles.md#builtin-item-attributes)
+See also: [The list of generic builtin item attributes](../repo/items.py.md#builtin-item-attributes)
 
-<br>
+<hr>
 
 ## installed