From 01726df4e8e2832ba4532e98c7090ba14e37bedc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Mon, 16 Dec 2019 11:00:24 +0100 Subject: [PATCH] doc: Restructure to allow better latex rendering --- docs/source/_templates/layout.html | 6 --- docs/source/concepts/toc.rst | 15 +++++++ docs/source/conf.py | 27 +++++++++++- .../examples/{index.rst => examples.rst} | 44 +++++++++---------- docs/source/examples/toc.rst | 6 +++ docs/source/index.rst | 39 ++++++++-------- docs/source/latextoc.rst | 7 +++ docs/source/the_project/toc.rst | 10 +++++ docs/source/tutorial/toc.rst | 11 +++++ 9 files changed, 116 insertions(+), 49 deletions(-) delete mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/concepts/toc.rst rename docs/source/examples/{index.rst => examples.rst} (96%) create mode 100644 docs/source/examples/toc.rst create mode 100644 docs/source/latextoc.rst create mode 100644 docs/source/the_project/toc.rst create mode 100644 docs/source/tutorial/toc.rst 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