Documentation update for v0.5.

Author: Fizzadar

docs/compatibility.rst

@@ -3,11 +3,11 @@ Compatibility
 
 pyinfra aims to be compatible with all Unix-like operating systems and is currently tested against:
 
-+ Ubuntu 14/16
-+ Debian 7/8
++ Ubuntu 14/15/16
++ Debian 7/8/9
 + CentOS 6/7
-+ Fedora 23
-+ OpenBSD 5.8
-+ macOS 10.12
++ Fedora 24
++ OpenBSD 6
++ macOS 10.13
 
 In general, the only requirement (beyond a SSH server) on the remote side is shell access. POSIX commands are used where possible for facts and operations, so most of the ``server`` and ``files`` operations should work anywhere POSIX.

docs/deploys.rst

@@ -103,7 +103,7 @@ The same keys can be defined for host and group data - this means we can set a d
 + Normal group data
 + "all" group data
 
-Debugging data issues:
+.. note::
     pyinfra contains a ``--debug-data`` option which can be used to explore the data output per-host for a given inventory/deploy.
 
 Data Example
@@ -180,16 +180,8 @@ For example, this deploy will ensure that user "pyinfra" exists with home direct
 
 Uses the :doc:`server module <./modules/server>` and :doc:`files module <./modules/files>`. You can see all the modules in :doc:`the modules index <./operations>`.
 
-Naming operations:
-    Pass a ``set`` object as the first argument to name the operation, which will appear during a deploy. By default the operation module, name and arguments are shown:
-
-.. code:: python
-
-    server.user(
-        {'Ensure user pyinfra'},  # the contents of the set will become the op name
-        'pyinfra',
-        home='/home/pyinfra'
-    )
+.. note::
+    Pass a ``set`` object as the first argument to name the operation (as above), which will appear during a deploy. By default the operation module, name and arguments are shown.
 
 Using Data
 ~~~~~~~~~~
@@ -208,7 +200,7 @@ Adding data to inventories was :ref:`described above <data-ref-label>` - you can
         home=host.data.app_dir,
     )
 
-String formatting:
+.. warning::
     pyinfra supports jinja2 style string arguments, which should be used over Python's builtin string formatting where you expect the final string to change per host. This is because pyinfra groups operations by their arguments. See: :doc:`using Python <./using_python>` for more information; an example of this is:
 
 .. code:: python
@@ -243,7 +235,7 @@ Operation meta can be used during a deploy to change the desired operations:
     with state.when(create_user.changed):
         server.shell('# add user to sudo, etc...')
 
-Conditionals:
+.. warning::
     pyinfra supports conditional branches with the ``state.limit`` and ``state.when`` control structures (as shown above). These should be used in place of normal Python ``if`` statements. This prevents operations being executed in unexpected orders. For more information, see: :doc:`using Python <./using_python>`.
 
 Facts
@@ -323,8 +315,8 @@ There are a number of configuration options for how deploys are managed. These c
     # Fail the entire deploy after 10% of hosts fail
     FAIL_PERCENT = 10
 
-config.py advantage:
-    When added to ``config.py``, these options will take affect when using pyinfra ``--fact`` or ``--run``.
+.. note::
+    When added to ``config.py`` (vs the deploy file), these options will take affect when using pyinfra ``--fact`` or ``--run``.
 
 
 Hooks

docs/example_deploy.png

@@ -9,12 +9,12 @@ match) and the client assets are then built before pyinfra connects to any hosts
 
 .. code:: python
 
-    # deploy.py
+    # config.py
 
     from pyinfra import hook, local
 
     @hook.before_connect
-    def build_assets(data, state):
+    def check_branch(data, state):
         # Check local branch matches the deploy branch
         branch = local.shell('git rev-parse --abbrev-ref HEAD')
         app_branch = data.app_branch
@@ -25,11 +25,13 @@ match) and the client assets are then built before pyinfra connects to any hosts
                 branch, app_branch
             ))
 
+    @hook.before_connect
+    def build_assets(data, state):
         # Prep for clientside build
         local.shell('npm prune')
         local.shell('npm install')
 
         # Build the assets (using webpack in this case)
         local.shell('webpack --progress')
 
-    # deploy operations...
+Simply place this ``config.py`` alongside your deploys and pyinfra will pick it up.

docs/patterns/client_side_assets.rst

@@ -117,7 +117,40 @@ footer#pagefooter {
         border: none;
     }
 
-/* Index only */
+div.admonition {
+    padding: 0;
+    border: none;
+}
+div.admonition p {
+    display: block !important;
+    padding: 5px;
+    margin: 0;
+}
+p.admonition-title {
+    font-weight: normal;
+}
+
+div.admonition.note {
+    background: #e7f2fa;
+}
+div.admonition.note p.admonition-title {
+    background: #6ab0de;
+    color: white;
+}
+
+div.admonition.warning {
+    background: #ffedcc;
+}
+div.admonition.warning p.admonition-title {
+    background: #f0b37e;
+    color: white;
+}
+
+
+/*
+    Index only
+*/
+
 div#pyinfra-documentation div.compound {
     width: 46%;
     margin-right: 3%;

docs/static/pyinfra.css

@@ -60,5 +60,5 @@ pyinfra also has a global ``limit`` keyword argument and a matching ``state.limi
         limit=inventory.get_host('my-host.net'),
     )
 
-Note:
-    pyinfra ensures that operations are always executed in order **per host**, so there's no risk of, say, trying to use ``docker`` before installing it.
+.. note::
+    Despite the above, pyinfra always ensures that operations are always executed in order **per host** so there's no risk of, say, trying to use ``docker`` before installing it.