Generate global kwargs doc from the config.

This means new global kwargs will be automatically documented!

.gitignore

@@ -19,6 +19,8 @@ venv/
 docs/build/
 docs/facts/
 docs/modules/
+docs/_deploy_globals.rst
+
 .idea/
 
 pyinfra-debug.log

docs/conf.py

@@ -57,6 +57,7 @@ def setup(app):
             mkdir(auto_docs_path)
 
     local.shell((
+        'python {0}/generate_global_kwargs_doc.py'.format(scripts_dir),
         'python {0}/generate_facts_docs.py'.format(scripts_dir),
         'python {0}/generate_modules_docs.py'.format(scripts_dir),
     ))

docs/deploys.rst

@@ -148,28 +148,7 @@ Global Arguments
 
 In addition to each operations own arguments, there are a number of keyword arguments available in all operations:
 
-Privilege & user escalation
-    + ``sudo=True``: Execute/apply any changes with sudo.
-    + ``sudo_user='username'``: Execute/apply any changes with sudo as a non-root user.
-    + ``su_user='username'``: Execute/apply any changes with su.
-    + ``preserve_sudo_env=True``: Preserve the shell environment when using sudo.
-
-Operation control:
-    + ``env``: Dictionary of environment variables to set.
-    + ``ignore_errors=True``: Ignore errors when excuting the operation.
-    + ``serial=True``: Run this operation host by host, rather than in parallel.
-    + ``parallel=10``: Run this operation in batches of hosts.
-    + ``run_once=True``: Only execute this operation once, on the first host to see it.
-    + ``timeout=10``: Timeout for *each* command executed during the operation.
-    + ``get_pty=True``: Whether to get a pseudoTTY when executing any commands.
-
-Callbacks:
-    + ``on_success=my_success_function``: Callback function to execute on success.
-    + ``on_error=my_error_function``: Callback function to execute on error.
-
-Limiting operations to subsets of the inventory:
-    + ``hosts='web'``: Limit the operation to a subset of the hosts (either a list of host objects or a group name).
-    + ``when=host.fact.os == 'Darwin'``: Limit the operaton based on a conditional/boolean.
+.. include:: _deploy_globals.rst
 
 Using Data
 ~~~~~~~~~~

scripts/generate_global_kwargs_doc.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+
+from os import path
+
+from pyinfra.api.operation_kwargs import OPERATION_KWARGS
+
+
+def build_global_kwargs_doc():
+    this_dir = path.dirname(path.realpath(__file__))
+    docs_dir = path.abspath(path.join(this_dir, '..', 'docs'))
+
+    lines = []
+
+    for category, kwarg_configs in OPERATION_KWARGS.items():
+        if category is None:
+            continue
+
+        lines.append('{0}:'.format(category))
+
+        for key, config in kwarg_configs.items():
+            description = config
+            if isinstance(config, dict):
+                description = config.get('description')
+
+            lines.append('    + ``{0}``: {1}'.format(key, description))
+
+    module_filename = path.join(docs_dir, '_deploy_globals.rst')
+    print('--> Writing {0}'.format(module_filename))
+
+    out = '\n'.join(lines)
+
+    with open(module_filename, 'w') as outfile:
+        outfile.write(out)
+
+
+if __name__ == '__main__':
+    print('### Building global kwargs doc')
+    build_global_kwargs_doc()