doc: typos and style fixes

docs/source/the_project/install_and_configure.rst

@@ -1,7 +1,7 @@
 Installing Kapow!
 =================
 
-*Kapow!* has a reference implementation in ``Go`` that is under active development
+*Kapow!* has a reference implementation in *Go* that is under active development
 right now.  If you want to start using *Kapow!* you can choose from several
 options.
 
@@ -20,7 +20,7 @@ Linux
 
 Install the downloaded binary using the following command as a privileged user.
 
-.. code-block:: bash
+.. code-block:: console
 
   $ install -t /usr/local/bin/kapow path_to_downloaded_binary
 
@@ -32,22 +32,50 @@ Copy the downloaded binary to a directory of your choice and update the system
 ``PATH`` variable to include that directory.
 
 
-Install the package with go get
+Install the package with ``go get``
--------------------------------
+-----------------------------------
 
 If you already have `installed and configured <https://golang.org/cmd/go/>`_
 the ``go`` runtime in the host where you want to run *Kapow!*, simply run:
 
-.. code-block:: bash
+.. code-block:: console
 
-  $ go get -u github.com/BBVA/kapow
+  $ go get -v github.com/BBVA/kapow
+
+Note that *Kapow!* leverages *Go modules*, so you can target specific releases:
+
+.. code-block:: console
+
+  $ GO111MODULE=on go get -v github.com/BBVA/kapow@v0.3.0-rc4
+  go: finding github.com v0.3.0-rc4
+  go: finding github.com/BBVA v0.3.0-rc4
+  go: finding github.com/BBVA/kapow v0.3.0-rc4
+  go: downloading github.com/BBVA/kapow v0.3.0-rc4
+  go: extracting github.com/BBVA/kapow v0.3.0-rc4
+  github.com/google/shlex
+  github.com/google/uuid
+  github.com/spf13/pflag
+  github.com/BBVA/kapow/internal/server/httperror
+  github.com/BBVA/kapow/internal/http
+  github.com/BBVA/kapow/internal/server/model
+  github.com/BBVA/kapow/internal/client
+  github.com/gorilla/mux
+  github.com/BBVA/kapow/internal/server/user/spawn
+  github.com/BBVA/kapow/internal/server/data
+  github.com/BBVA/kapow/internal/server/user/mux
+  github.com/BBVA/kapow/internal/server/user
+  github.com/BBVA/kapow/internal/server/control
+  github.com/spf13/cobra
+  github.com/BBVA/kapow/internal/server
+  github.com/BBVA/kapow/internal/cmd
+  github.com/BBVA/kapow
 
 
 Include *Kapow!* in your Container Image
 ----------------------------------------
 
-If you want to include *Kapow!* in a ``Docker`` image you can add the binary
+If you want to include *Kapow!* in a ``Docker`` image, you can add the binary
-directly from the releases section. Following is an example ``Dockerfile`` that
+directly from the releases section.  Below is an example ``Dockerfile`` that
 includes *Kapow!*.
 
 .. code-block:: dockerfile
@@ -63,15 +91,15 @@ includes *Kapow!*.
   ENTRYPOINT ["/usr/bin/kapow"]
 
 If the container is intended for running the server and you want to dinamically
-configure it, remember to include a `--control-bind` param with an external bind
+configure it, remember to include a ``--control-bind`` param with an external
-address (i.e. ``0.0.0.0``) and to map all the needed ports in order to get access
+bind address (e.g., ``0.0.0.0``) and to map all the needed ports in order to get
-to the control interface.
+access to the control interface.
 
 After building the image you can run the container with:
 
-.. code-block:: bash
+.. code-block:: console
 
   $ docker run --rm -i -p 8080:8080 -v $(pwd)/whatever.pow:/opt/whatever.pow kapow:latest server /opt/whatever.pow
 
-With the `-v` parameter we map a local file into the container's filesystem so
+With the ``-v`` parameter we map a local file into the container's filesystem so
 we can use it to configure our *Kapow!* server on startup.

docs/source/the_project/quickstart.rst

@@ -19,15 +19,18 @@ this:
 Our organization has an external host that acts as a bridge between our intranet
 an the public Internet.
 
-**Our goal: Our team needs to check if the** :samp:`Internal Host` **is alive.**
+**Our goal: Our team must be able to check if the :samp:`Internal Host` is alive on an ongoing basis.**
 
 
 Limitations and Constraints
 ---------------------------
 
-1. We **don't want** to **grant access** to the :samp:`*External Host*` to anybody.
+1. We **don't want** to **grant access** to the :samp:`External Host` to
-2. We **don't want** to manage VPNs or any similar solutions to access :samp:`Internal Host` from the Internet.
+   anybody.
-3. We **want to limit the actions** that a user can perform in our intranet while it is checking if :samp:`Internal Host` is alive.
+2. We **don't want** to manage VPNs or any similar solutions to access
+   :samp:`Internal Host` from the Internet.
+3. We **want to limit the actions** that a user can perform in our intranet
+   while it is checking if :samp:`Internal Host` is alive.
 4. We **want** to use the most standard mechanism.  Easy to use and automate.
 5. We **don't have a budget** to invest in a custom solution.
 
@@ -35,7 +38,7 @@ Limitations and Constraints
 The Desired Solution
 --------------------
 
-After analyzing the problem and our with our goal in mind, we conclude that it
+After analyzing the problem and with our goal in mind, we conclude that it
 is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`.
 
 So, the next step is to **analyze how to perform the ping.**
@@ -44,9 +47,9 @@ So, the next step is to **analyze how to perform the ping.**
 Accessing via SSH to :samp:`External Host`
 ++++++++++++++++++++++++++++++++++++++++++
 
-If we choose this option then we need to create a user in the host and grant
+If we choose this option, then, for every person that needs to check the status
-them access via :samp:`SSH` to :samp:`External Host` for every person that needs
+of :samp:`Internal host`, we need to create a user in the ``Extarnal Host`` and
-to check the :samp:status of `Internal host`.
+grant them ``SSH`` access.
 
 Conclusion: **Not a good idea.**
 
@@ -80,10 +83,14 @@ Using *Kapow!* (spoiler: it's the winner!)
 
 Ok, let's analyze *Kapow!* and check if it is compatible with our constraints:
 
-1. *Kapow!* is Open Source, so **it's also free as in beer**.
+1. *Kapow!* is Open Source, so it's also **free as in beer**.
-2. By using kapow! we don't need to code our own solution, so we **don't have to waste time**.
+2. By using *Kapow!* we don't need to code our own solution, so we **don't have
-3. By using *Kapow!* we can run any command in the :samp:`External Host` limiting the command parameters, so **it's safe**.
+   to waste time**.
-4. By using *Kapow!* we can launch any system command as an HTTP API easily, so **we don't need to grant login access to anybody to** :samp:`External Host`.
+3. By using *Kapow!* we can run any command in the :samp:`External Host`
+   limiting the command parameters, so **it's safe**.
+4. By using *Kapow!* we can launch any system command as an ``HTTP API`` easily, so
+   **we don't need to grant login access to** :samp:`External Host` **to
+   anybody**.
 
 Conclusion: *Kapow!* **is the best choice.**
 
@@ -93,19 +100,20 @@ Reasons: It satisfies all of our requirements.
 Using Kapow!
 ------------
 
-In order to get our example :ref:`Scenario <quickstart_image>` working we need to follow the below steps.
+In order to get our example :ref:`Scenario <quickstart_image>` working we need
+to follow the steps below.
 
 
 Install Kapow!
 ++++++++++++++
 
-Follow :doc:`Install *Kapow!* <install_and_configure>` instructions.
+Follow the :doc:`Installing Kapow! <install_and_configure>` instructions.
 
 
 Write a ``ping.pow`` File
 +++++++++++++++++++++++++
 
-*Kapow!* uses plain text files (called ``POW`` files) so you can define the
+*Kapow!* uses plain text files (called ``pow`` files) so you can define the
 endpoints you want to expose the system command with.  For our example we need a
 file like this:
 
@@ -116,16 +124,21 @@ file like this:
 
 Explanation:
 
-1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the *Kapow!* server.  You have to use `GET` method to invoke the endpoint.
+1. :samp:`kapow route add /ping` - adds a new ``HTTP API`` endpoint at :samp:`/ping`
-2. :samp:`-c` - after this parameter we write the system command that *Kapow!* will run each time the endpoint is invoked.
+   path in the *Kapow!* server.  You have to use ``GET`` method to invoke the
-3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`.
+   endpoint.
-4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body of the response, so you can see it.
+2. :samp:`-c` - after this parameter we write the system command that *Kapow!*
+   will run each time the endpoint is invoked.
+3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host
+   *10.10.10.100*, i.e. :samp:`Internal Host`.
+4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body
+   of the response, so you can see it.
 
 
 Launch the Service
 ++++++++++++++++++
 
-At this point we only need to launch `kapow` with our :samp:`ping.pow`:
+At this point we only need to launch ``kapow`` with our :samp:`ping.pow`:
 
 .. code-block:: console
 

docs/source/the_project/security.rst

@@ -61,12 +61,11 @@ The command that will eventually be executed by ``bash`` is:
 
    find -delete | kapow set /response/body
 
-This will silently delete all the files below the current directory, no
+This will *silently delete all the files below the current directory*, no
 questions asked.  Probably not what you expected.
 
 This happens because ``find`` has the last word on how to interpret its arguments.
-For ``find`` the argument `-delete` is not a path,
+For ``find``, the argument `-delete` is not a path.
-
 
 Let's see how we can handle this particular case:
 
@@ -83,4 +82,4 @@ Let's see how we can handle this particular case:
 
    Since this is critical for keeping your *Kapow!* services secure, we are working
    on a way to make this more transparent and safe, while at the same time keeping
-   it Kapowy.
+   it *Kapowy*.

docs/source/tutorial/index.rst

@@ -1,13 +1,13 @@
 *Kapow!* Tutorial
 =================
 
-  This tutorial will allow you to grow slowly in the knowledge of *Kapow!*.  It
+  This tutorial will help you to get more familiar with *Kapow!*.  It tells you
-  tells you the story of a senior ops guy just arrived to his new job in a small
+  the story of a senior ops guy just arrived to his new job in a small company.
-  company.  He'll face different challenges of increasing difficulty, but with
+  He'll face different challenges of increasing difficulty, but with the help of
-  the help of his experienced senior mate and *Kapow!* he will be able to satisfy
+  his experienced senior mate and *Kapow!* he will be able to pass all the
-  all the requierements.
+  hurdles.
 
-  You just only need to follow the steps and execute the code shown in the
+  You just need to follow the steps and execute the code shown in the tutorial
-  tutorial to learn the *Kapow!* way of doing.
+  to learn *the Kapow! way*.
 
-  Have a nice trip to Kapow!
+  Enjoy the ride!