diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
deleted file mode 100644
index 0c206d2..0000000
--- a/docs/source/_templates/layout.html
+++ /dev/null
@@ -1,6 +0,0 @@
-{% extends "!layout.html" %}
-
- {% block menu %}
- Welcome to Kapow!
- {{ super() }}
- {% endblock %}
diff --git a/docs/source/concepts/toc.rst b/docs/source/concepts/toc.rst
new file mode 100644
index 0000000..0aafce6
--- /dev/null
+++ b/docs/source/concepts/toc.rst
@@ -0,0 +1,15 @@
+Concepts
+========
+
+This section is a contains a reference of all the important *Kapow!*
+concepts that you should know.
+
+.. toctree::
+ :hidden:
+
+ interfaces
+ philosophy
+ request_life_cycle
+ resource_tree
+ route_matching
+ routes
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 1d120b3..b5fc4bc 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -28,6 +28,7 @@ author = 'BBVA Innovation Labs'
# ones.
extensions = [
'sphinx.ext.todo',
+ 'sphinx.ext.imgconverter'
]
# Add any paths that contain templates here, relative to this directory.
@@ -46,6 +47,7 @@ rst_prolog = """
:class: xref
.. default-role:: tech
+
"""
# -- Options for HTML output -------------------------------------------------
@@ -58,7 +60,7 @@ html_logo = "_static/logo-200px.png"
html_theme_options = {
'logo_only': True,
'collapse_navigation': False,
- 'navigation_depth': 4,
+ 'navigation_depth': 3,
'includehidden': True,
'titles_only': False
@@ -71,3 +73,26 @@ html_static_path = ['_static']
# https://stackoverflow.com/a/56448499
master_doc = 'index'
+
+latex_logo = '_static/logo.png'
+latex_documents = [
+ ('latextoc',
+ 'kapow.tex',
+ 'Kapow! Documentation',
+ 'BBVA Innovation Labs',
+ 'manual',
+ True)
+]
+
+man_pages = [
+ ('concepts/resource_tree',
+ 'kapow-resources',
+ 'Kapow! Resource Tree Reference',
+ 'BBVA Innovation Labs',
+ 1),
+ ('examples/examples',
+ 'kapow-examples',
+ 'Kapow! Usage Examples',
+ 'BBVA Innovation Labs',
+ 1),
+]
diff --git a/docs/source/examples/index.rst b/docs/source/examples/examples.rst
similarity index 96%
rename from docs/source/examples/index.rst
rename to docs/source/examples/examples.rst
index 82ff7a4..0d2187c 100644
--- a/docs/source/examples/index.rst
+++ b/docs/source/examples/examples.rst
@@ -1,12 +1,12 @@
Using a pow File
-++++++++++++++++
+----------------
A :file:`pow` file is just a :command:`bash` script, where you make calls to the
``kapow route`` command.
Starting *Kapow!* using a pow file
-----------------------------------
+++++++++++++++++++++++++++++++++++
.. code-block:: console
:linenos:
@@ -34,7 +34,7 @@ With the :file:`example.pow`:
Load More Than One pow File
-+++++++++++++++++++++++++++
+---------------------------
You can load more than one :file:`pow` file at time. This can help you keep
your :file:`pow` files tidy.
@@ -48,7 +48,7 @@ your :file:`pow` files tidy.
Add a New Route
-+++++++++++++++
+---------------
.. warning::
@@ -56,7 +56,7 @@ Add a New Route
same path, only the first route added will be used.
GET route
----------
++++++++++
Defining a route:
@@ -75,7 +75,7 @@ Calling route:
hello world
POST route
-----------
+++++++++++
Defining a route:
@@ -95,7 +95,7 @@ Calling a route:
Adding URL params
------------------
++++++++++++++++++
Defining a route:
@@ -115,7 +115,7 @@ Calling a route:
Listing Routes
-++++++++++++++
+--------------
You can list the active routes in the *Kapow!* server.
@@ -151,7 +151,7 @@ Or, if you want human-readable output, you can use :program:`jq`:
Deleting Routes
-+++++++++++++++
+---------------
You need the ID of a route to delete it.
Running the command used in the :ref:`listing routes example
@@ -165,7 +165,7 @@ it by typing:
Writing Multiline pow Files
-+++++++++++++++++++++++++++
+---------------------------
If you need to write more complex actions, you can leverage multiline commands:
@@ -190,7 +190,7 @@ If you need to write more complex actions, you can leverage multiline commands:
Add or Modify an HTTP Header
-++++++++++++++++++++++++++++
+----------------------------
You may want to add some extra HTTP header to the response.
@@ -245,7 +245,7 @@ Testing with :program:`curl`:
Modify JSON by Using Shell Commands
-+++++++++++++++++++++++++++++++++++
+-----------------------------------
.. note::
@@ -256,7 +256,7 @@ Modify JSON by Using Shell Commands
Example #1
-----------
+++++++++++
In this example our *Kapow!* service will receive a `JSON` value with an incorrect
date, then our ``pow`` file will fix it and return the correct value to the user.
@@ -282,7 +282,7 @@ Call the service with :program:`curl`:
Example #2
-----------
+++++++++++
In this example we extract the ``name`` field from the incoming `JSON` document in
order to generate a two-attribute `JSON` response.
@@ -313,10 +313,10 @@ Call the service with :program:`curl`:
Upload Files
-++++++++++++
+------------
Example #1
-----------
+++++++++++
Uploading a file using *Kapow!* is very simple:
@@ -338,7 +338,7 @@ Uploading a file using *Kapow!* is very simple:
Example #2
-----------
+++++++++++
In this example we reply the line count of the file received in the request:
@@ -370,7 +370,7 @@ In this example we reply the line count of the file received in the request:
Protecting Against Parameter Injection Attacks
-++++++++++++++++++++++++++++++++++++++++++++++
+----------------------------------------------
When you resolve variable values be careful to tokenize correctly by using
double quotes. Otherwise you could be vulnerable to **parameter injection
@@ -418,7 +418,7 @@ request:
Sending HTTP error codes
-++++++++++++++++++++++++
+------------------------
You can specify custom status code for `HTTP` response:
@@ -455,7 +455,7 @@ Testing with :program:`curl`:
How to redirect using HTTP
-++++++++++++++++++++++++++
+--------------------------
In this example we'll redirect our users to `Google`:
@@ -490,7 +490,7 @@ In this example we'll redirect our users to `Google`:
How to Execute Two Processes in Parallel
-++++++++++++++++++++++++++++++++++++++++
+----------------------------------------
We want to :command:`ping` two machines parallel. *Kapow!* can get IP addresses
from query params:
@@ -514,7 +514,7 @@ Calling with :program:`curl`:
Manage Cookies
-++++++++++++++
+--------------
If you track down some user state, *Kapow!* allows you manage Request/Response
Cookies.
diff --git a/docs/source/examples/toc.rst b/docs/source/examples/toc.rst
new file mode 100644
index 0000000..29ebca9
--- /dev/null
+++ b/docs/source/examples/toc.rst
@@ -0,0 +1,6 @@
+Examples
+========
+
+.. toctree::
+
+ examples
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 5e18353..952ca49 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -14,41 +14,41 @@ Welcome to *Kapow!*
What's *Kapow!*
-===============
+---------------
- Think of that software that you need but **only runs in the command
- line**. *Kapow!* lets you wrap it into an `HTTP API` **real easy**.
+Think of that software that you need but **only runs in the command
+line**. *Kapow!* lets you wrap it into an `HTTP API` **real easy**.
- .. image:: _static/kapow-quick-overview.png
- :width: 80%
- :align: center
+.. image:: _static/kapow-quick-overview.png
+ :width: 80%
+ :align: center
- Want to know more?
- Check the :ref:`Quick Start Guide ` section for a longer
- explanation of what *Kapow!* does.
+Want to know more?
+Check the :ref:`Quick Start Guide ` section for a longer
+explanation of what *Kapow!* does.
Authors
-=======
+-------
- *Kapow!* is being developed by the `BBVA-Labs Security team`_.
+*Kapow!* is being developed by the `BBVA-Labs Security team`_.
License
-=======
+-------
- *Kapow!* is Open Source Software and available under the `Apache 2 license`_.
+*Kapow!* is Open Source Software and available under the `Apache 2 license`_.
Contributions
-=============
+-------------
- Contributions are of course welcome. See `CONTRIBUTING`_ or skim `existing
- tickets`_ to see where you could help out.
+Contributions are of course welcome. See `CONTRIBUTING`_ or skim
+`existing tickets`_ to see where you could help out.
-Table of Contents
-=================
+Contents
+========
.. toctree::
:maxdepth: 2
@@ -62,7 +62,6 @@ Table of Contents
:maxdepth: 2
:caption: Tutorial
- tutorial/index
tutorial/tutorial00
tutorial/tutorial01
tutorial/tutorial02
@@ -74,7 +73,7 @@ Table of Contents
:maxdepth: 2
:caption: Usage Examples
- examples/index
+ examples/examples
.. toctree::
:maxdepth: 2
diff --git a/docs/source/latextoc.rst b/docs/source/latextoc.rst
new file mode 100644
index 0000000..435bf3f
--- /dev/null
+++ b/docs/source/latextoc.rst
@@ -0,0 +1,7 @@
+.. toctree::
+ :maxdepth: 3
+
+ the_project/toc
+ tutorial/toc
+ examples/toc
+ concepts/toc
diff --git a/docs/source/the_project/toc.rst b/docs/source/the_project/toc.rst
new file mode 100644
index 0000000..b4ec1d1
--- /dev/null
+++ b/docs/source/the_project/toc.rst
@@ -0,0 +1,10 @@
+The Project
+===========
+
+This section will introduce you to *Kapow!* basics.
+
+.. toctree::
+
+ quickstart
+ security
+ install_and_configure
diff --git a/docs/source/tutorial/toc.rst b/docs/source/tutorial/toc.rst
new file mode 100644
index 0000000..1544e0a
--- /dev/null
+++ b/docs/source/tutorial/toc.rst
@@ -0,0 +1,11 @@
+.. include:: index.rst
+
+.. toctree::
+ :caption: Chapters
+
+ tutorial00
+ tutorial01
+ tutorial02
+ tutorial03
+ tutorial04
+ tutorial05