Documentation WIP

README.rst

@@ -1,49 +1,42 @@
-With *Kapow!* you can publish simple **shell scripts** as **HTTP
-services**.
+Welcome to *Kapow!*
+===================
 
-This way you can delegate in others its execution as they don't need access to the host in
-which the command is ran. In summary, those repetitive tasks that everybody ask you to do
-because they require administrative access to some host can be published through
-a *Kapow!* server deployed in that host and the users who need the results can
-invoke it directly using an easy to use interface, an HTTP request.
+With *Kapow!* you can publish simple **shell scripts** as **HTTP services** easily.
 
-.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png
-    :alt: Where Kapow! lives
+*Kapow!* with an example
+------------------------
 
-Installation
-============
+**Goal**
 
-1. Get a precompiled static binary for your system from our `releases section <https://github.com/BBVA/kapow/releases/latest>`_.
+We want users on the Internet to be able to ``ping`` an *Internal Host*
+which is inside a private network.
 
-2. Put it in your ``$PATH`` (Linux example):
+.. image:: _static/network.png
 
-   .. code-block:: bash
+**Limitations**
 
-      sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow
+- We can't allow users to log into any host. 
 
+- We need to have full control over the precise command is run as
+  well as the parameters used.
 
-Hello World! -- *Kapow!* style
-==============================
+**Solution**
 
-In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
-Let's publish it through HTTP using *Kapow!*
+With a *Kapow!* one-liner you can allow your users to run a command inside
+*External Host* through an HTTP call.
 
-- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
+.. image:: _static/sequence.png
+
+This is the only line you'll need:
 
 .. code-block:: bash
 
-    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
+   $ kapow route add /ping -c 'ping -c1 10.10.10.100 | kapow set /response/body'
 
-- Start the *Kapow!* server with your script as an argument
 
-.. code-block:: bash
+.. todo::
 
-    kapow server greet.sh
+   Mention license and contributing
 
-- Finally check that all is working as intended using `curl`
 
-.. code-block:: bash
-
-    $ curl http://localhost:8080/greet
-    Hello World!
 

docs/Pipfile

@@ -10,4 +10,4 @@ sphinx = "*"
 sphinx-rtd-theme = "*"
 
 [requires]
-python_version = "3.7"
+python_version = "3.8"

docs/source/conf.py

@@ -48,7 +48,12 @@ exclude_patterns = []
 html_theme = "sphinx_rtd_theme"
 html_logo = "_static/logo.png"
 html_theme_options = {
-    'logo_only': True
+    'logo_only': True,
+    'collapse_navigation': False,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/index.rst

@@ -2,14 +2,17 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: TODO
 
-Quickstart Guide
-================
+   install
+   quickstart
 
-.. todo::
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorial
+
+   tutorial
 
-   Here an end to end tutorial (15-20 minutes)
 
 
 Indices and tables

docs/source/install.rst

@@ -0,0 +1,17 @@
+Installation
+============
+
+Precompiled Binaries
+--------------------
+
+1. Get a precompiled static binary for your system from our `releases section <https://github.com/BBVA/kapow/releases/latest>`_.
+
+2. Put it in your ``$PATH`` (Linux example):
+
+   .. code-block:: bash
+
+      sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow
+
+.. todo::
+
+   Describe all the options available.

docs/source/quickstart.rst

@@ -0,0 +1,27 @@
+Quickstart Guide
+================
+
+
+Hello World! -- *Kapow!* style
+------------------------------
+
+In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
+Let's publish it through HTTP using *Kapow!*
+
+- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
+
+.. code-block:: bash
+
+    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
+
+- Start the *Kapow!* server with your script as an argument
+
+.. code-block:: bash
+
+    kapow server greet.sh
+
+- Finally check that all is working as intended:
+
+.. image:: _static/browser.png
+
+

docs/source/tutorial.rst

@@ -0,0 +1,28 @@
+
+.. todo::
+
+   Redo 
+
+Hello World! -- *Kapow!* style
+------------------------------
+
+In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
+Let's publish it through HTTP using *Kapow!*
+
+- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
+
+.. code-block:: bash
+
+    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
+
+- Start the *Kapow!* server with your script as an argument
+
+.. code-block:: bash
+
+    kapow server greet.sh
+
+- Finally check that all is working as intended:
+
+.. image:: _static/browser.png
+
+