From e6cb0f1fa6367e2a4db4651d829b011637fabc1d Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Wed, 11 Dec 2019 02:37:56 +0100 Subject: [PATCH] doc: fix typo and rst style fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per the official docs¹, we should use ``code`` instead of :samp:`code`, since we are not enhancing variables inside. :samp: A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in file. For example, in :samp:`print 1+{variable}`, the part variable would be emphasized. If you don’t need the “variable part” indication, use the standard ``code`` instead. ¹: https://www.sphinx-doc.org/en/1.5/markup/inline.html#role-samp --- docs/source/examples/index.rst | 6 ++--- docs/source/the_project/quickstart.rst | 34 +++++++++++++------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 423c16d..d7a5407 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -123,7 +123,7 @@ You can list the active routes in the *Kapow!* server. $ kapow route list [{"id":"20c98328-0b82-11ea-90a8-784f434dfbe2","method":"GET","url_pattern":"/echo/{message}","entrypoint":"/bin/sh -c","command":"kapow get /request/matches/message | kapow set /response/body"}] -Or, if you want human-readable output, you can use :samp:`jq`: +Or, if you want human-readable output, you can use ``jq``: .. code-block:: console :linenos: @@ -175,7 +175,7 @@ If you need to write more complex actions, you can leverage multiline commands: .. warning:: Be aware of the **"-"** at the end of the ``kapow route add`` command. - It tells ``kapow route add`` to read commands from :samp:`stdin`. + It tells ``kapow route add`` to read commands from ``stdin``. .. warning:: @@ -482,7 +482,7 @@ In this example we'll redirect our users to Google: How to Execute Two Processes in Parallel ++++++++++++++++++++++++++++++++++++++++ -We want to :samp:`ping` two machines parallel. *Kapow!* can get IPs from query +We want to ``ping`` two machines parallel. *Kapow!* can get IPs from query params: .. code-block:: console diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index 8e4979a..250bf99 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -19,18 +19,18 @@ this: Our organization has an external host that acts as a bridge between our intranet an the public Internet. -**Our goal: Our team must be able to check if the :samp:`Internal Host` is alive on an ongoing basis.** +**Our goal: Our team must be able to check if the ``Internal Host`` is alive on an ongoing basis.** Limitations and Constraints --------------------------- -1. We **don't want** to **grant access** to the :samp:`External Host` to +1. We **don't want** to **grant access** to the ``External Host`` to anybody. 2. We **don't want** to manage VPNs or any similar solutions to access - :samp:`Internal Host` from the Internet. + ``Internal Host`` from the Internet. 3. We **want to limit the actions** that a user can perform in our intranet - while it is checking if :samp:`Internal Host` is alive. + while it is checking if ``Internal Host`` is alive. 4. We **want** to use the most standard mechanism. Easy to use and automate. 5. We **don't have a budget** to invest in a custom solution. @@ -39,16 +39,16 @@ The Desired Solution -------------------- After analyzing the problem and with our goal in mind, we conclude that it -is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`. +is enough **to use a simple** ``ping`` **to** ``Internal Host``. So, the next step is to **analyze how to perform the ping.** -Accessing via SSH to :samp:`External Host` +Accessing via SSH to ``External Host`` ++++++++++++++++++++++++++++++++++++++++++ If we choose this option, then, for every person that needs to check the status -of :samp:`Internal host`, we need to create a user in the ``Extarnal Host`` and +of ``Internal host``, we need to create a user in the ``External Host`` and grant them ``SSH`` access. Conclusion: **Not a good idea.** @@ -57,7 +57,7 @@ Reasons: 1. We need to manage users (violates a constraint.) 2. We need to grant usesrs access to a host (violates a constraint.) - 3. We can't control what :samp:`ping` options the user can use to ping :samp:`Internal Host` (violates a constraint.) + 3. We can't control what ``ping`` options the user can use to ping ``Internal Host`` (violates a constraint.) Develop and Deploy a Custom Solution @@ -86,10 +86,10 @@ Ok, let's analyze *Kapow!* and check if it is compatible with our constraints: 1. *Kapow!* is Open Source, so it's also **free as in beer**. 2. By using *Kapow!* we don't need to code our own solution, so we **don't have to waste time**. -3. By using *Kapow!* we can run any command in the :samp:`External Host` +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 ``HTTP API`` easily, so - **we don't need to grant login access to** :samp:`External Host` **to + **we don't need to grant login access to** ``External Host`` **to anybody**. Conclusion: *Kapow!* **is the best choice.** @@ -124,21 +124,21 @@ file like this: Explanation: -1. :samp:`kapow route add /ping` - adds a new ``HTTP API`` endpoint at :samp:`/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. :samp:`-c` - after this parameter we write the system command that *Kapow!* +2. ``-c`` - after this parameter we write the system command that *Kapow!* will run each time the endpoint is invoked. -3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host - *10.10.10.100*, i.e. :samp:`Internal Host`. -4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body +3. ``ping -c 1 10.10.10.100`` - sends 1 ping package to the host + *10.10.10.100*, i.e. ``Internal Host``. +4. ``| kapow set /response/body`` - writes the output of `ping` to the body of the response, so you can see it. Launch the Service ++++++++++++++++++ -At this point we only need to launch ``kapow`` with our :samp:`ping.pow`: +At this point we only need to launch ``kapow`` with our ``ping.pow``: .. code-block:: console @@ -149,7 +149,7 @@ Consume the Service +++++++++++++++++++ Now we can call our newly created endpoint by using our favorite HTTP client. -In this example we're using :samp:`curl`: +In this example we're using ``curl``: .. code-block:: console