Filling out README and expanding the setup utility

This also includes a setup.cfg to aid linting tools

README.md

@@ -1,13 +1,144 @@
-# ansible_kernel
+# Ansible Jupyter Kernel
 
-## To install:
+![Example Jupyter Usage](https://raw.githubusercontent.com/ansible/ansible-jupyter-kernel/master/docs/example_session.png)
+
+The Ansible [Jupyter](http://jupyter.readthedocs.io/en/latest/) Kernel adds a kernel backend for Jupyter to interface directly with Ansible and construct plays and tasks and execute them on the fly.
+
+## Table of Contents
+
+* [Installation](#installation)
+  * [From pypi](#from-pypi)
+  * [From a local checkout](#from-a-local-checkout)
+* [Usage](#usage)
+  * [Using the cells](#using-the-cells)
+  * [Examples](#examples)
+* [Using the development environment](#using-the-development-environment)
+
+## Installation:
+
+`ansible-kernel` is available to be installed from pypi but you can also install it locally. The setup package itself will register the kernel
+with `Jupyter` automatically.
+
+### From pypi
+
+    pip install ansible-kernel
+
+### From a local checkout
 
     pip install -e .
-    python -m ansible_kernel.install
 
-## To use it:
+## Usage
 
 ```
     jupyter notebook
     # In the notebook interface, select Ansible from the 'New' menu
 ```
+
+### Using the Cells
+
+Normally `Ansible` brings together various components in different files and locations to launch a playbook and performs automation tasks. For this
+`jupyter` interface you need to provide this information in cells by denoting what the cell contains and then finally writing your tasks that will make
+use of them. There are [Examples](#examples) available to help you, in this section we'll go over the currently supported cell types.
+
+In order to denote what the cell contains you should prefix it with a pound/hash symbol (#) and the type as listed here as the first line as shown in the examples
+below.
+
+#### #inventory
+
+The inventory that your tasks will use
+
+```
+#inventory
+[all]
+ahost ansible_connection=local
+anotherhost examplevar=val
+```
+
+#### #play
+
+This represents the opening block of a typical `Ansible` play
+
+```
+#play
+name: Hello World
+hosts: all
+gather_facts: false
+```
+
+#### #task
+
+This is the default cell type if no type is given for the first line
+
+```
+#task
+debug:
+```
+
+```
+#task
+shell: cat /tmp/afile
+register: output
+```
+
+#### #host_vars
+
+#### #group_vars
+
+#### #vars
+
+This takes an argument that represents the filename for use in later cells
+
+```
+#vars example_vars
+message hello vars
+```
+
+```
+#play
+name: hello world
+hosts: localhost
+gather_facts: false
+vars_files:
+    - example_vars
+```
+
+#### #template
+
+This takes an argument in order to create a templated file that can be used in later cells
+
+```
+#template hello.j2
+{{ message }}
+```
+
+```
+#task
+template:
+    src: hello.j2
+    dest: /tmp/hello
+```
+
+#### #ansible.cfg
+
+Provides overrides typically found in ansible.cfg
+
+```
+#ansible.cfg
+[defaults]
+host_key_checking=False
+```
+
+### Examples
+
+You can find various [example notebooks in the repository](https://github.com/ansible/ansible-jupyter-kernel/tree/master/notebooks)
+
+## Using the development environment
+
+It's possible to use whatever python development process you feel comfortable with. The repository itself includes mechanisms for
+using [pipenv](https://github.com/pypa/pipenv)
+
+```
+pipenv install
+...
+pipenv shell
+```

setup.cfg

@@ -0,0 +1,23 @@
+[pep8]
+# E201 - Whitespace after '('
+# E203 - Whitespace before ":"
+# E221 - Multiple spaces after operator
+# E225 - Missing whitespace around operator
+# E231 - Missing whitespace after ','
+# E241 - Multiple spaces after ','
+# E251 - Unexpected spaces around keyword / parameter equals
+# E261 - At least two spaces before inline comment
+# E302 - Expected 2 blank lines found 0
+# E303 - Too many blank lines
+# W291 - Trailing whitespace
+# W391 - Blank line at end of file
+# W293 - Blank line contains whitespace
+ignore=E201,E203,E221,E225,E231,E241,E251,E261,E265,E303,W291,W391,W293
+
+[flake8]
+max-line-length=160
+ignore=E201,E203,E221,E225,E231,E241,E251,E261,E265,E303,W291,W391,W293,E731,F405
+
+[metadata]
+license_file=LICENSE.md
+description-file = README.md

setup.py

@@ -1,12 +1,48 @@
+import json
+import os
 from setuptools import setup, find_packages
+from setuptools.command.install import install
+
+
+class Installer(install):
+    def run(self):
+        # Regular install
+        install.run(self)
+
+        # Post install
+        print('Installing Ansible Kernel kernelspec')
+        from jupyter_client.kernelspec import KernelSpecManager
+        from IPython.utils.tempdir import TemporaryDirectory
+        kernel_json = {
+            "argv": ["python", "-m", "ansible_kernel", "-f", "{connection_file}"],
+            "codemirror_mode": "yaml",
+            "display_name": "Ansible",
+            "language": "ansible"
+        }
+        with TemporaryDirectory() as td:
+            os.chmod(td, 0o755)
+            with open(os.path.join(td, 'kernel.json'), 'w') as f:
+                json.dump(kernel_json, f, sort_keys=True)
+            ksm = KernelSpecManager()
+            ksm.install_kernel_spec(td, 'ansible', user=self.user, replace=True, prefix=self.prefix)
+
+
+
+with open('README.md', 'r') as f:
+    long_description = f.read()
 
 setup(
-    name='ansible_kernel',
-    version='0.0.1',
+    name='ansible-kernel',
+    version='0.1',
+    description='An Ansible kernel for Jupyter',
+    long_description=long_description,
     packages=find_packages(),
+    cmdclass={'install': Installer},
+    license='Apache',
     install_requires=[
         'PyYAML',
         'psutil',
+        'jupyter',
     ],
     zip_safe=False
 )