Sphinx documentation quickstart plus README.md and README.rst merge.

2019-11-14 10:11:19 +01:00
parent 0618e55ce0
commit 95a6c7597f
9 changed files with 178 additions and 160 deletions
@@ -3,3 +3,6 @@ __pycache__
 output
 build
 .vscode
 docs/build
 docs/Pipfile.lock
@@ -1,48 +0,0 @@
 # What is it?
 Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service.
 It lies between these two worlds, making your life easier.
 Kapow! allows yo to publish a simple shell script as a REST HTTP service so you
 can delegate in others its execution as they don't need access to the host in
 which the command is ran.  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 a easy to use interfaz, a HTTP request.
 In the tradicional way you needed to create a project, manage its dependencies,
 code the server (probably including only a command execution) and deploy it
 somewhere.  And that's fine... until you find yourself again in the same
 situation with another awesome command.
 ### From now on you can put Kapow! into action
 - Create a pow file containing an api call to Kapow! for creating the route
 that will publish your command, lets's call it `greet.pow`
  ```sh
    kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body'
  ```
 - Start the Kapow! server providing your pow file to configure the route
  ```sh
    kapow server greet.pow
  ```
 - check that all it is working as intended using `curl`
  ```sh
    $ curl localhost:8080/greet
    Hello World
    $ curl localhost:8080/greet?name=friend
    Hello friend
  ```
 # Installing Kapow!
 Kapow! has a reference implementation in Go that is under active development right
 now.  If you want to start using Kapow! you can:
 * Download a binary (only linux is available , at this moment) from our
 [releases](https://github.com/BBVA/kapow/releases/latest) section
 * Install the package with Go's `get` command (you need the Go runtime installed
 and [configured](https://golang.org/cmd/go/))
 ```sh
 go get -u github.com/BBVA/kapow
 ```
@@ -1,131 +1,49 @@
-.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png
+With *Kapow!* you can publish simple **shell scripts** as **HTTP
-    :alt: Kapow!
+services**.
-.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg
+This way you can delegate in others its execution as they don't need access to the host in
-    :target: https://circleci.com/gh/BBVA/kapow/tree/master
+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
-**Kapow!** If you can script it, you can HTTP it.
+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.
 CAVEAT EMPTOR
 =============
 **Warning!!! Kapow!** is under **heavy development** and `specification </spec>`_;
 the provided code is a Proof of Concept and the final version will not even
 share programming language.  Ye be warned.
 What is it?
 ===========
 Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service.
 Some tasks are more convenient in the shell, like cloud interactions, or some
 administrative tools.  On the other hand, some tasks are more convenient as a
 service, like DevSecOps tooling.
 Kapow! lies between these two worlds, making your life easier.  Maybe you wonder
 about how this kind of magic can happen; if you want to know the nitty-gritty
 details, just read our `specification </spec>`_;.  Or, if you want to know how
 Kapow! can help you first, let's start with a common situation.
 Think about that awesome command that you use every day, something very
 familiar, like ``cloudx storage ls /backups``.  Then someone asks you for an
 specific backup, so you ``ssh`` into the host, execute your command, possibly
 ``grepping`` through its output, copy the result and send it back to him.
 And that's fine... for the 100 first times.
 Then you decide, let's use an API for this and generate an awesome web server
 with it.  So, you create a project, manage its dependencies, code the server,
 parse the request, learn how to use the API, call the API and deploy it
 somewhere.  And that's fine... until you find yourself again in the same
 situation with another awesome command.
 The awesomeness of UNIX® commands is infinite, so you'll be in this situation
 an infinite number of times!  Instead, let's put Kapow! into action.
 With Kapow! you just need to create a ``.pow`` file named ``backups.pow`` that
 contains:
 .. code-block:: sh
    kapow route add /backups \
        -c 'cloudx storage ls /backups | grep $(kapow get /request/params/query) | kapow set /response/body'
 and execute it in the remote host with the command:
 .. code-block:: sh
    kapow server backups.pow
 and that's it.  Done.  You have a web server that people can use to request
 their backups every time they need only by invoking the URL
 `http://remotehost/backups?query=project`
 Do you like it? yes?  Then let's start learning a little more, you can access
 the `documentation </doc>`_; section to find installation instructions and some
 examples.
 How it was born
 ---------------
 Some awesome history is coming.
 Kapow! for the impatient
 ========================
 When you need to **share** a ``command`` but **not** a complete remote ``ssh
 access``, Kapow!  will help you with the power of HTTP:
 .. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png
    :alt: Where Kapow! lives
-Kapow! allows you to write a litte script that will **serve an executable as REST
+Installation
-service**.  This script will let you define how to connect HTTP and the  Shell
+============
 using Kapow!'s shell abstractions to the HTTP world. See it to believe:
-.. image:: resources/kapow.gif?raw=true
+1. Get a precompiled static binary for your system from our `releases section <https://github.com/BBVA/kapow/releases/latest>`_.
-    :alt: Kapow! in action
+
 2. Put it in your ``$PATH`` (Linux example):
   .. code-block:: bash
      sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow
-Superpowers
+Hello World! -- *Kapow!* style
-----------
+==============================
-Kapow! gives you:
+In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
 Let's publish it through HTTP using *Kapow!*
-* A very simple way to turn any shell **executable into an API**
+- 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:
 * A **remote administration** API
 * A way to define the integration in you own terms, obligations-free!
 .. code-block:: bash
-Curses
+    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
 ------
-Kapow! can't help when:
+- Start the *Kapow!* server with your script as an argument
 -----------------------
-* You need high throughput: Kapow! spawns a new executable for every HTTP call
+.. code-block:: bash
 * You must perform complex logic to attend the request: never use Kapow! if
  your executables don't perform al least 90% of the hard work
 * You are building a huge application
    kapow server greet.sh
-When it is your best friend:
+- Finally check that all is working as intended using `curl`
 --------------------------
-* Easy command + Hard API = Kapow! to the rescue
+.. code-block:: bash
 * SSH for one command?  Kapow! allows you to share only that command
 * Remote instrumentation of several machines?  Make it easy with Kapow!
    $ curl http://localhost:8080/greet
    Hello World!
 The more you know
 =================
 If you want to know more, please follow our `documentation </doc>`_.
@@ -0,0 +1,20 @@
 # Minimal makefile for Sphinx documentation
 #
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 .PHONY: help Makefile
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1,13 @@
 [[source]]
 name = "pypi"
 url = "https://pypi.org/simple"
 verify_ssl = true
 [dev-packages]
 [packages]
 sphinx = "*"
 sphinx-rtd-theme = "*"
 [requires]
 python_version = "3.7"
@@ -0,0 +1,35 @@
@ECHO OFF
 pushd %~dp0
 REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
 set BUILDDIR=build
 if "%1" == "" goto help
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
 	echo.installed, then set the SPHINXBUILD environment variable to point
 	echo.to the full path of the 'sphinx-build' executable. Alternatively you
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
 	echo.http://sphinx-doc.org/
 	exit /b 1
 )
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 :end
 popd
@@ -0,0 +1,57 @@
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 # -- Path setup --------------------------------------------------------------
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 # -- Project information -----------------------------------------------------
 project = 'Kapow!'
 copyright = '2019, BBVA Innovation Labs'
 author = 'BBVA Innovation Labs'
 # -- General configuration ---------------------------------------------------
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
    'sphinx.ext.todo',
 ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 # -- Options for HTML output -------------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
 html_logo = "_static/logo.png"
 html_theme_options = {
    'logo_only': True
 }
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
@@ -0,0 +1,20 @@
 .. include:: ../../README.rst
 .. toctree::
   :maxdepth: 2
   :caption: Contents:
 Quickstart Guide
 ================
 .. todo::
   Here an end to end tutorial (15-20 minutes)
 Indices and tables
 ==================
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`