Badly needed formatting fixes (#1)

* Quickstart

* It worked

* Create README.md

* Polishing

* Inner linking

* Fixing bad formatting

* WIP

* Fixing last of the links I think

README.md

@@ -0,0 +1,2 @@
+# gort-guide
+The user documentation for Gort.

guide/source/sections/architecture.rst

@@ -95,7 +95,9 @@ Command bundles can only be installed by an adequately-privileged user
 Relays
 ~~~~~~
 
-*This section describes a planned feature that doesn't yet exist.*
+.. caution::
+
+   This section describes a planned feature that doesn't yet exist.
 
 Optionally, relays can be tagged with identifiers so that commands can
 be executed preferentially by specific relays installed in specific
@@ -116,7 +118,9 @@ executing the image with the appropriate command and arguments.
 Local Command Execution
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-*This section describes a planned feature that doesn't yet exist.*
+.. caution::
+
+   This section describes a planned feature that doesn't yet exist.
 
 If so directed in the command bundle (and allowed by the security
 settings), a worker is capable of executing a command directly on the
@@ -125,7 +129,9 @@ relay's host.
 Message Bus
 -----------
 
-*This section describes a planned feature that doesn't yet exist.*
+.. caution::
+
+   This section describes a planned feature that doesn't yet exist.
 
 The Gort controller and the relays communicate via a dedicated message
 bus, typically Kafka.

guide/source/sections/bundle-configurations.rst

@@ -6,10 +6,6 @@ Gort, may be executed by users from any connected (and allowed) chat
 service. A bundle configuration specifies which binary to execute, and
 who may execute the commands (i.e., which users with which permissions).
 
-.. raw:: html
-
-   <!-- *Currently, Gort only supports commands that have been built into a Docker image, but a future iteration will support the execution of commands natively on a relay's host.* -->
-
 A Minimal Bundle Configurations
 -------------------------------
 
@@ -27,7 +23,7 @@ A minimal bundle configuration looks like the following:
 
     commands:
       date:
-        executable: [ "/usr/local/bin/mydate" ]
+        executable: [ "/bin/date" ]
         description: "Displays the current date and time"
         rules:
           - allow
@@ -64,7 +60,7 @@ Commands
 
 Commands are possibly the most complex component of the bundle config.
 
-As an example let’s look at an excerpt from the config for a ``ec2``
+As an example let’s look at an excerpt from the config for an ``ec2``
 bundle.
 
 .. code:: yaml
@@ -92,8 +88,7 @@ several fields.
 
 -  ``rules`` is a required list of strings that define what permissions
    are required to run the command. In this example, the ``ec2:view``
-   permission is required. See `Permissions and
-   Rules <permissions-and-rules.md>`__ to learn more about rules and
+   permission is required. See :doc:`permissions-and-rules` to learn more about rules and
    their construction.
 
 Permissions
@@ -153,12 +148,6 @@ configuration:
    explanation of required arguments or about the structure of the
    output.
 
-.. raw:: html
-
-   <!-- * `examples` is how a user will run the command and what output they should expect.
-
-   * `notes` is a free-form section at the bottom of the command above author and homepage -->
-
 Bundle Installation
 -------------------
 
@@ -167,7 +156,7 @@ Command bundles can be explicitly installed using
 adequately-privileged user (an administrator or other user with the
 ``gort:manage_bundles`` permission), and are disabled by default.
 
-See `Managing Bundles <managing-bundles.md>`__ for more information on
+See :doc:`managing-bundles` for more information on
 how to explicitly install command bundles.
 
 A Complete Bundle Configuration Example

guide/source/sections/command-bundles.rst

@@ -11,13 +11,14 @@ Bundle Configurations
 
 A bundle configuration is a `YAML <https://yaml.org/>`__-formatted
 document that describes a single bundle, including its name,
-description, version, `container image <commands-as-containers.md>`__,
+description, version, `container image <commands-as-containers.html>`__,
 and one or more commands. Additionally, each command definition includes
 a name, description, and which binary in the container to execute when
 the command is triggered by a user.
 
-See `Bundle Configurations <bundle-configurations.md>`__ for more
-information.
+.. tip::
+
+    See :doc:`bundle-configurations` for more information.
 
 Permissions and Rules
 ---------------------
@@ -30,8 +31,9 @@ so installing a bundle's permissions will never conflict with any
 existing rules. Except for ``admin``, permissions are never
 automatically assigned to users.
 
-See `Permissions and Rules <permissions-and-rules.md>`__ for more
-information.
+.. tip::
+
+    See :doc:`permissions-and-rules` for more information.
 
 Writing a Command Bundle
 ------------------------
@@ -42,8 +44,9 @@ all the binaries and other dependencies for executing one or more
 commands. They also include some data about the commands, including a
 small amount of documentation and other metadata.
 
-See `Writing A Command Bundle <writing-a-command-bundle.md>`__ for more
-specifics.
+.. tip::
+
+    See :doc:`writing-a-command-bundle` for more information.
 
 Managing Bundles
 ----------------
@@ -52,5 +55,6 @@ Bundles can be installed into Gort by an administrator (or any user with
 the ``manage_commands`` permission) using the ``gort`` command-line
 utility.
 
-See `Managing Bundles <managing-bundles.md>`__ for more on bundle
-installation.
+.. tip::
+
+    See :doc:`managing-bundles` for more information.

guide/source/sections/commands-and-bundles.rst

@@ -74,8 +74,7 @@ the executables in your terminal.
 
 A given command may need some additional information that would not be
 shared on the "shared command line", but will have to be setup by an
-administrator, such as an OAuth key. See `Dynamic Command
-Configuration <dynamic-command-configuration.md>`__ for more information
+administrator, such as an OAuth key. See :doc:`dynamic-command-configuration` for more information
 on how to get this data for command execution.
 
 Bundles
@@ -88,13 +87,11 @@ Each references a single `Docker container
 image <https://www.docker.com/resources/what-container>`__ that contains
 all the binaries and other dependencies for executing one or more
 commands. They also include some data about the commands, including a
-small amount of documentation and other metadata. See `Writing A Command
-Bundle <writing-a-command-bundle.md>`__ for more specifics.
+small amount of documentation and other metadata. See :doc:`writing-a-command-bundle` for more specifics.
 
 Bundles can be installed into Gort by an administrator (or any user with
 the ``manage_commands`` permission) using the ``gort`` command-line
-utility. See `Managing Bundles <managing-bundles.md>`__ for more on
-bundle installation.
+utility. See :doc:`managing-bundles` for more on bundle installation.
 
 Bundle Permissions and Rules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -162,16 +159,16 @@ Implementation Details
 
 Every bundle has a Docker image that contains all of its commands.
 
-By default, the command uses the image's `default
-entrypoint <https://docs.docker.com/engine/reference/builder/#entrypoint>`__
+By default, the command uses the image's `default entrypoint <https://docs.docker.com/engine/reference/builder/#entrypoint>`__ 
 to handle commands. However, if a command has an ``executable`` defined,
-then the given binary is used instead (like a `Docker ``--entrypoint``
+then the given binary is used instead (like a `Docker --entrypoint 
 parameter <https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime>`__).
 
 Any parameters you type into the command line are passed directly to the
 containerized binary, which can handle them just like a normal
 command-line execution. This allows you to implement your command using
 a CLI framework in any language you like.
 
-See `Commands as Containers <commands-as-containers.md>`__ for more
-details.
+.. tip::
+
+    See :doc:`commands-as-containers` for more details.

guide/source/sections/commands-as-containers.rst

@@ -1,8 +1,7 @@
 Commands As Containers
 ======================
 
-As you may recall from `Commands and
-Bundles <commands-and-bundles.md>`__, the *command bundle* is the
+As you may recall from :doc:`commands-and-bundles`, the *command bundle* is the
 packaging unit for a collection of one or more actions triggerable by a
 user, collectively referred to as "commands". Each bundle references a
 single `Docker container
@@ -34,22 +33,20 @@ Job <https://kubernetes.io/docs/concepts/workloads/controllers/job/>`__
 resource to manage the container.
 
 In both cases, the new command container gets several default
-`Environment Variables <command-environment-variables.md>`__ that can be
+`Environment Variables <command-environment-variables.html>`__ that can be
 useful for command processes.
 
 Executing the Command
 ---------------------
 
 However it's created, the new container executes the ``executable``
 specified in the bundle command. If an ``executable`` isn't specified in
-the command, the container's `default
-``ENTRYPOINT`` <https://docs.docker.com/engine/reference/builder/#entrypoint>`__
+the command, the container's `default ENTRYPOINT <https://docs.docker.com/engine/reference/builder/#entrypoint>`__
 is used instead.
 
 By allowing a different ``executable`` value to be set for each command
 in a bundle, it becomes possible for a single container to contain many
-commands. See `Writing a Command Bundle <writing-a-command-bundle.md>`__
-for more information.
+commands. See :doc:`writing-a-command-bundle` for more information.
 
 Command Parameters
 ------------------
@@ -94,13 +91,11 @@ Presentation
 
 Finally, the output is presented to the user. If the output consists of
 valid JSON, it will be sent to the templating engine and transformed
-according to the appropriate `Output Formatting
-Templates <templates.md>`__ (you don't have to worry about that now --
+according to the appropriate :doc:`templates` (you don't have to worry about that now --
 there are perfectly reasonable defaults). Otherwise the output will be
 formatted for the user as simple, monospaced text.
 
 Additional Reading
 ------------------
 
-Discussions of constructing commands and formatting its output at
-`Writing a Command Bundle <writing-a-command-bundle.md>`__
+Discussions of constructing commands and formatting its output at :doc:`writing-a-command-bundle`

guide/source/sections/configuration.rst

@@ -44,7 +44,7 @@ Generic placeholders are defined as follows:
 -  ``<port>``: a valid port number ranging from 0 to 65535.
 -  ``<secret>``: a regular string that is a secret, such as a password.
 -  ``<string>``: a regular string.
--  ``<template>``: a Gort `output formatting template <templates.md>`__.
+-  ``<template>``: a Gort `output formatting template <templates.html>`__.
 
 The other placeholders are specified separately.
 
@@ -298,7 +298,7 @@ internal trace telemetry.
 -----------
 
 The ``templates`` section allows the default `output formatting
-templates <templates.md>`__ to be overridden at the application scope.
+templates <templates.html>`__ to be overridden at the application scope.
 Templates defined here may still be overridden at the bundle and command
 scopes.
 

guide/source/sections/deployment.rst

@@ -6,8 +6,7 @@ controller.
 
 The Gort controller is the core Gort service, which relays messages to
 and from the chat providers, manages relay command instructions, and
-exposes the REST administration API. See `Gort
-Architecture <architecture.md>`__ for more information.
+exposes the REST administration API. See :doc:`architecture` for more information.
 
 Running Gort in Kubernetes
 --------------------------
@@ -20,8 +19,7 @@ Prerequisites
 ~~~~~~~~~~~~~
 
 You'll need to have `Helm <https://helm.sh/>`__ installed. If you don't,
-you can follow the `instructions
-here <https://helm.sh/docs/intro/install/>`__.
+you can follow the `instructions here <https://helm.sh/docs/intro/install/>`__.
 
 Deployment
 ~~~~~~~~~~

guide/source/sections/getting-started.rst

@@ -3,8 +3,7 @@ Getting Started
 
 The Gort controller is the core Gort service. It relays messages to and
 from the chat providers, manages relay command instructions, and exposes
-the REST administration API. See `Gort Architecture <architecture.md>`__
-for more information.
+the REST administration API. See :doc:`architecture` for more information.
 
 This guide will instruct you through the process of configuring,
 installing, running, and bootstrapping the Gort controller.
@@ -23,23 +22,29 @@ reload" its by sending it a SIGHUP or issuing a ``GET`` request to its
 ``v2/reload/`` endpoint. If the new configuration is not well-formed,
 the changes will not be applied.
 
-See `Configuring Gort <configuration.md>`__ for more detail.
+.. tip::
+
+    See :doc:`configuration` for more detail.
 
 Deploying Gort
 --------------
 
 Gort can be installed in a variety of ways: it can be run as a
 standalone binary, or as a Docker container, or in Kubernetes.
 
-See `Deploying Gort <deployment.md>`__ for more detail.
+.. tip::
+
+    See :doc:`deployment` for more detail.
 
 Bootstrapping Gort
 ------------------
 
 Once Gort is deployed, the database must be set up and the initial
 administration user defined, a process referred to as "bootstrapping".
 Once Gort is properly bootstrapped, the administrator will be able to
-`manage users <managing-users.md>`__, `install and enable command
-bundles <managing-bundles.md>`__, and more.
+`manage users <managing-users.html>`__, `install and enable command
+bundles <managing-bundles.html>`__, and more.
 
-See `Bootstrapping Gort <bootstrapping.md>`__ for more detail.
+.. tip::
+
+    See :doc:`bootstrapping` for more detail.

guide/source/sections/installing-your-first-command-bundle.rst

@@ -11,9 +11,7 @@ To create a bundle, you first need a bundle configuration: a
 YAML-formatted file that supplies Gort with all of the information it
 needs to install and execute commands in your bundle.
 
-For a detailed description of bundle configurations, go to the `Bundle
-Configurations <bundle-configurations.md>`__ section in the
-documentation.
+For a detailed description of bundle configurations, go to the :doc:`bundle-configurations` section in the documentation.
 
 For our example we will be using the following config. It's a simple
 bundle with only one un-enforcing command. Just create a file named
@@ -42,7 +40,7 @@ or ``.yml``.
 
 If your commands specify any rules, other than the special "allow" rule,
 you will need to make sure the proper grants are in place. Check out
-`Permissions and Rules <permissions-and-rules.md>`__ to learn more.
+:doc:`permissions-and-rules`` to learn more.
 
 Bundles are most easily created with Gort's command line interface:
 ``gort``. To create your bundle just type the following at the command

guide/source/sections/managing-bundles.rst

@@ -4,7 +4,7 @@ Managing Bundles
 This document details the commands used to manage bundles.
 
 Currently, all command bundles are executed on the same machine as the
-Gort Controller. In `a future release <going-forward.md>`__, support for
+Gort Controller. In `a future release <going-forward.html>`__, support for
 "relays" will be added, which will allow commands to be executed on
 different machines running a Relay process.
 
@@ -36,8 +36,7 @@ specified in the bundle's metadata.
 
 Importantly, after installation your bundle command will be available,
 but may not be usable yet. Before anyone can execute the new commands,
-make sure their user permissions are set properly. See `Permissions and
-Rules <permissions-and-rules.md>`__ to learn more.
+make sure their user permissions are set properly. See :doc:`permissions-and-rules` to learn more.
 
 Bundles are installed via the ``bundle install`` sub-command in
 ``gort``.