doc: Restructure to allow better latex rendering

2019-12-16 11:00:24 +01:00
parent 9a52a7192a
commit 01726df4e8
9 changed files with 116 additions and 49 deletions
@@ -1,6 +0,0 @@
-{% extends "!layout.html" %}
-
-  {% block menu %}
-    <a href="index.html">Welcome to <em>Kapow!</em></a>
-    {{ super() }}
-  {% endblock %}
@@ -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
@@ -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),
+]
@@ -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.
@@ -0,0 +1,6 @@
+Examples
+========
+
+.. toctree::
+
+   examples
@@ -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
+.. image::  _static/kapow-quick-overview.png
   :width: 80%
   :align: center

-  Want to know more?
-  Check the :ref:`Quick Start Guide <quickstart>` section for a longer
-  explanation of what *Kapow!* does.
+Want to know more?
+Check the :ref:`Quick Start Guide <quickstart>` 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
@@ -0,0 +1,7 @@
+.. toctree::
+   :maxdepth: 3
+
+   the_project/toc
+   tutorial/toc
+   examples/toc
+   concepts/toc
@@ -0,0 +1,10 @@
+The Project
+===========
+
+This section will introduce you to *Kapow!* basics.
+
+.. toctree::
+
+   quickstart
+   security
+   install_and_configure
@@ -0,0 +1,11 @@
+.. include:: index.rst
+
+.. toctree::
+   :caption: Chapters
+
+   tutorial00
+   tutorial01
+   tutorial02
+   tutorial03
+   tutorial04
+   tutorial05