Sphinx documentation quickstart plus README.md and README.rst merge.
This commit is contained in:
Roberto Abdelkader Martínez Pérez
@@ -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
|
||||
```
|
||||
+30
-112
@@ -1,131 +1,49 @@
|
||||
.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png
|
||||
:alt: Kapow!
|
||||
With *Kapow!* you can publish simple **shell scripts** as **HTTP
|
||||
services**.
|
||||
|
||||
.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg
|
||||
:target: https://circleci.com/gh/BBVA/kapow/tree/master
|
||||
|
||||
**Kapow!** If you can script it, you can HTTP it.
|
||||
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
.. 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
|
||||
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:
|
||||
Installation
|
||||
============
|
||||
|
||||
.. image:: resources/kapow.gif?raw=true
|
||||
:alt: Kapow! in action
|
||||
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
|
||||
|
||||
|
||||
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**
|
||||
* A **remote administration** API
|
||||
* A way to define the integration in you own terms, obligations-free!
|
||||
- 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
|
||||
|
||||
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
|
||||
* 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
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
* SSH for one command? Kapow! allows you to share only that command
|
||||
* Remote instrumentation of several machines? Make it easy with Kapow!
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
@@ -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`
|
||||
Reference in New Issue
Block a user