From ab615e227672c16ae35a685ac3b80aa21888f4be Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Wed, 11 Dec 2019 15:59:27 +0100 Subject: [PATCH] doc: markup :any: role as default role, which is now :tech: (custom) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Roberto Abdelkader Martínez Pérez --- docs/source/concepts/interfaces.rst | 6 +++--- docs/source/concepts/philosophy.rst | 2 +- docs/source/concepts/request_life_cycle.rst | 8 ++++---- docs/source/concepts/routes.rst | 6 +++--- docs/source/examples/index.rst | 14 +++++++------- docs/source/index.rst | 2 +- .../the_project/install_and_configure.rst | 4 ++-- docs/source/the_project/quickstart.rst | 6 +++--- docs/source/tutorial/tutorial05.rst | 18 +++++++++--------- 9 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/source/concepts/interfaces.rst b/docs/source/concepts/interfaces.rst index b4dbf5d..7a6bd51 100644 --- a/docs/source/concepts/interfaces.rst +++ b/docs/source/concepts/interfaces.rst @@ -8,7 +8,7 @@ clear purpose. User Interface -------------- -The :any:`User HTTP Interface` is used to serve final user requests. +The `User HTTP Interface` is used to serve final user requests. By default it binds to address ``0.0.0.0`` and port ``8080``, but that can be changed via the ``--bind`` flag. @@ -17,7 +17,7 @@ changed via the ``--bind`` flag. Control Interface ----------------- -The :any:`Control HTTP Interface` is used by the command ``kapow route`` to +The `Control HTTP Interface` is used by the command ``kapow route`` to administer the list of system routes. By default it binds to address ``127.0.0.1`` and port ``8081``, but that can be @@ -27,7 +27,7 @@ changed via the ``--control-bind`` flag. Data Interface -------------- -The :any:`Data HTTP Interface` is used by the commands ``kapow get`` and ``kapow +The `Data HTTP Interface` is used by the commands ``kapow get`` and ``kapow set`` to exchange the data for a particular request. By default it binds to address ``127.0.0.1`` and port ``8082``, but that can be diff --git a/docs/source/concepts/philosophy.rst b/docs/source/concepts/philosophy.rst index 62d8201..20279ed 100644 --- a/docs/source/concepts/philosophy.rst +++ b/docs/source/concepts/philosophy.rst @@ -7,7 +7,7 @@ Single Static Binary - Deployment is then as simple as it gets. -- :any:`Docker`-friendly. +- `Docker`-friendly. Shell Agnostic diff --git a/docs/source/concepts/request_life_cycle.rst b/docs/source/concepts/request_life_cycle.rst index 0ef65e0..468e8a5 100644 --- a/docs/source/concepts/request_life_cycle.rst +++ b/docs/source/concepts/request_life_cycle.rst @@ -2,7 +2,7 @@ Request Life Cycle ================== This section describes the sequence of events happening for each request -answered by the :any:`User HTTP Interface`. +answered by the `User HTTP Interface`. .. image:: ../_static/request_life_cycle.png @@ -10,7 +10,7 @@ answered by the :any:`User HTTP Interface`. 1. request ---------- -The user makes a request to the :any:`User HTTP Interface`. +The user makes a request to the `User HTTP Interface`. - The request is matched against the route table. @@ -30,8 +30,8 @@ The spawned entrypoint is run with the following variables added to its environment: - :envvar:`KAPOW_HANDLER_ID`: Containing the `HANDLER_ID` -- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the :any:`Data HTTP Interface` -- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the :any:`Control HTTP Interface` +- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the `Data HTTP Interface` +- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the `Control HTTP Interface` 3. ``kapow set /response/body banana`` diff --git a/docs/source/concepts/routes.rst b/docs/source/concepts/routes.rst index 4f8fe38..daa9a62 100644 --- a/docs/source/concepts/routes.rst +++ b/docs/source/concepts/routes.rst @@ -2,7 +2,7 @@ Routes ====== A *Kapow!* route specifies the matching criteria for an incoming request on -the :any:`User HTTP Interface`, and the details to handle it. +the `User HTTP Interface`, and the details to handle it. *Kapow!* implements a *route table* where all routes reside. @@ -79,7 +79,7 @@ which is an incomplete recipe. It is then completed by the `command` element. .. note:: - The semantics of this element closely match :any:`Docker`'s ``ENTRYPOINT`` directive. + The semantics of this element closely match `Docker`'s ``ENTRYPOINT`` directive. .. todo:: @@ -104,7 +104,7 @@ incantation to be executed: .. note:: - The semantics of this element closely match :any:`Docker`'s ``COMMAND`` directive. + The semantics of this element closely match `Docker`'s ``COMMAND`` directive. .. todo:: diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 7b7548e..fa0a270 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -142,7 +142,7 @@ Or, if you want human-readable output, you can use :program:`jq`: .. note:: - *Kapow!* has a :any:`Control HTTP Interface`, bound by default to + *Kapow!* has a `Control HTTP Interface`, bound by default to ``localhost:8081`` @@ -244,15 +244,15 @@ Modify JSON by Using Shell Commands .. note:: - Nowadays Web services are :any:`JSON`-based, so making your script :any:`JSON` aware is - probably a good choice. In order to be able to extract data from a :any:`JSON` - document as well as composing :any:`JSON` documents from a script, you can leverage + Nowadays Web services are `JSON`-based, so making your script `JSON` aware is + probably a good choice. In order to be able to extract data from a `JSON` + document as well as composing `JSON` documents from a script, you can leverage `jq `_. **Example #1** -In this example our *Kapow!* service will receive a :any:`JSON` value with an incorrect +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. .. code-block:: console @@ -277,8 +277,8 @@ Call the service with :program:`curl`: **Example #2** -In this example we extract the ``name`` field from the incoming :any:`JSON` document in -order to generate a two-attribute :any:`JSON` response. +In this example we extract the ``name`` field from the incoming `JSON` document in +order to generate a two-attribute `JSON` response. .. code-block:: console diff --git a/docs/source/index.rst b/docs/source/index.rst index feff9c7..2204858 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,7 +17,7 @@ What's *Kapow!* =============== Think of that **software** that you need but **only runs in the command - line**. *Kapow!* lets you **wrap it into an :any:`HTTP API` in the easiest + line**. *Kapow!* lets you **wrap it into an `HTTP API` in the easiest way possible**. .. image:: _static/kapow-quick-overview.png diff --git a/docs/source/the_project/install_and_configure.rst b/docs/source/the_project/install_and_configure.rst index 04cd1b8..2506fd1 100644 --- a/docs/source/the_project/install_and_configure.rst +++ b/docs/source/the_project/install_and_configure.rst @@ -1,7 +1,7 @@ Installing *Kapow!* =================== -*Kapow!* has a reference implementation in :any:`Go` that is under active +*Kapow!* has a reference implementation in `Go` that is under active development right now. If you want to start using *Kapow!* you can choose from several options. @@ -74,7 +74,7 @@ Note that *Kapow!* leverages *Go modules*, so you can target specific releases: Include *Kapow!* in your Container Image ---------------------------------------- -If you want to include *Kapow!* in a :any:`Docker` image, you can add the binary +If you want to include *Kapow!* in a `Docker` image, you can add the binary directly from the releases section. Below is an example :file:`Dockerfile` that includes *Kapow!*. diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index 3735208..9abbfde 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -89,7 +89,7 @@ Ok, let's analyze *Kapow!* and check if it is compatible with our constraints: to waste time**. 3. By using *Kapow!* we can run any command in the ``External Host`` limiting the command parameters, so **it's safe**. -4. By using *Kapow!* we can launch any system command as an :any:`HTTP API` easily, so +4. By using *Kapow!* we can launch any system command as an `HTTP API` easily, so **we don't need to grant login access to** ``External Host`` **to anybody**. @@ -125,7 +125,7 @@ file like this: Explanation: -1. ``kapow route add /ping`` - adds a new :any:`HTTP API` endpoint at ``/ping`` +1. ``kapow route add /ping`` - adds a new `HTTP API` endpoint at ``/ping`` path in the *Kapow!* server. You have to use ``GET`` method to invoke the endpoint. 2. ``-c`` - after this parameter we write the system command that *Kapow!* @@ -172,4 +172,4 @@ following diagram: :width: 80% As you can see, *Kapow!* provides the necessary *magic* to turn a **system -command** into an :any:`HTTP API`. +command** into an `HTTP API`. diff --git a/docs/source/tutorial/tutorial05.rst b/docs/source/tutorial/tutorial05.rst index e3c94e3..caf95db 100644 --- a/docs/source/tutorial/tutorial05.rst +++ b/docs/source/tutorial/tutorial05.rst @@ -29,7 +29,7 @@ Sharing the Stats **Senior** - We have to provide a new endpoint to serve the same data but in :any:`JSON` + We have to provide a new endpoint to serve the same data but in `JSON` format. **Junior** @@ -46,7 +46,7 @@ Sharing the Stats **Senior** - For starters, that's not valid :any:`JSON`. The output would be something like: + For starters, that's not valid `JSON`. The output would be something like: .. code-block:: console @@ -55,7 +55,7 @@ Sharing the Stats Mem: 31967 3121 21680 980 7166 27418 Swap: 0 0 0"} - You can't add new lines inside a :any:`JSON` string that way, you have to escape + You can't add new lines inside a `JSON` string that way, you have to escape the new line characters as ``\n``. **Junior** @@ -77,15 +77,15 @@ Sharing the Stats **Senior** - :program:`jq` is a wonderful tool for working with :any:`JSON` data from the command - line. With :program:`jq` you can extract data from a :any:`JSON` document and it also - allows you to generate a well-formed :any:`JSON` document. + :program:`jq` is a wonderful tool for working with `JSON` data from the command + line. With :program:`jq` you can extract data from a `JSON` document and it also + allows you to generate a well-formed `JSON` document. **Junior** Let's use it, then! - How can we generate a :any:`JSON` document with :program:`jq`? + How can we generate a `JSON` document with :program:`jq`? **Senior** @@ -104,7 +104,7 @@ Sharing the Stats **Senior** - Bear with me, it gets better. You can add variables to the :any:`JSON` and + Bear with me, it gets better. You can add variables to the `JSON` and :program:`jq` will escape them for you. .. code-block:: console @@ -165,7 +165,7 @@ Sharing the Stats **Junior** - I don't think so! the :any:`JSON` is well-formed and it contains all the required + I don't think so! the `JSON` is well-formed and it contains all the required data. And the code is quite readable. **Senior**