From 7bc075037b19898f1f065879033724642575d1e8 Mon Sep 17 00:00:00 2001
From: Arie Peterson <arie@greenhost.nl>
Date: Tue, 9 Jun 2020 14:26:10 +0200
Subject: [PATCH] More slight improvements to installation docs

---
 docs/installation_instructions.rst | 52 +++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 16 deletions(-)

diff --git a/docs/installation_instructions.rst b/docs/installation_instructions.rst
index a85fe6ae5..d5afff68f 100644
--- a/docs/installation_instructions.rst
+++ b/docs/installation_instructions.rst
@@ -178,7 +178,10 @@ Option A: Setup with the Greenhost API
    7. Copy the generated key and run export it to this variable in a
       terminal:
    
-      ``$ export COSMOS_API_TOKEN=<paste your API key here>``
+      ::
+      
+        $ export COSMOS_API_TOKEN=<paste your API key here>
+
    8. In *the same terminal*, you can now use the ``create`` subcommand
 
 - There are two ways to let the installation program know which VPS to use:
@@ -210,14 +213,25 @@ Option A: Setup with the Greenhost API
   If you use a subdomain (e.g. ``oas.yourdomain.com``), use the
   ``--subdomain`` command as follows:
 
-  ``$ python -m openappstack my-cluster create --subdomain oas example.org``
+  ::
 
-- Here is an example of a complete creation command:
+    $ python -m openappstack my-cluster create --subdomain oas example.org
 
-  ``$ python -m openappstack my-cluster create --create-droplet --create-hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org``
+- Here is an example of a complete creation command:
 
-    **NOTE:** You can use the ``--acme-staging`` argument for testing
-    purposes This ensures you use "staging" certificates from Let's
+  ::
+  
+    $ python -m openappstack my-cluster create \
+      --create-droplet \
+      --create-hostname oas.example.org \
+      --ssh-key-id 112 \
+      --create-domain-records \
+      --subdomain oas \
+      example.org
+
+  .. note::
+    You can use the ``--acme-staging`` argument for testing
+    purposes. This ensures you use "staging" certificates from Let's
     Encrypt, to reduce the stress on their servers. However, ONLYOFFICE
     integration requires valid (live) certificates to work.
 
@@ -244,12 +258,13 @@ you already have a machine with a world-facing IP address. Make sure
 that your VPS meets our `prerequisites <#prerequisites>`__. You'll need
 its *hostname* and its *IP address*.
 
-    **NOTE:** You can use the ``--acme-staging`` argument for testing
-    purposes. If you are automating this, please use this to ensure you
-    use "staging" certificates from Let's Encrypt, to reduce the stress
-    on their servers. However, ONLYOFFICE and single sign-on integration
-    require valid (live) certificates to work properly so please don't
-    use this option by default.
+.. note::
+  You can use the ``--acme-staging`` argument for testing
+  purposes. If you are automating this, please use this to ensure you
+  use "staging" certificates from Let's Encrypt, to reduce the stress
+  on their servers. However, ONLYOFFICE and single sign-on integration
+  require valid (live) certificates to work properly so please don't
+  use this option by default.
 
 If you want your cluster to be reachable under the fully qualified
 domain name (``FQDN``) ``oas.example.org``, the corresponding parameters
@@ -263,7 +278,11 @@ command:
 
 ::
 
-    $ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
+    $ python -m openappstack my-cluster create \
+      --ip-address IP_ADDRESS \
+      --create-hostname my-clusters-hostname \
+      --subdomain oas \
+      example.org 
 
 DNS entries
 '''''''''''
@@ -282,8 +301,9 @@ everything inside it. For example, create an A record for these domains:
 
 .. Note::
    It is also possible to host OpenAppStack on a domain (with
-   no dedicated subdomain). In that case, make these DNS records
-   instead:
+   no dedicated subdomain). That does imply that the included Wordpress site
+   will be hosted on your root domain ``example.org``. In that case, make these
+   DNS records instead:
 
    - An ``A`` record ``example.org`` pointing to the VPSs IP address,
    - A ``CNAME`` record ``*.example.org`` pointing to ``example.org``.
@@ -352,7 +372,7 @@ depending on your machine's compute and/or network resources.
 
 In the future, we will add commands that show you the status of the
 application installation. For now, just wait half an hour for everything
-to settle, and then continue to the Usage section.
+to settle, and then continue to the next step (validating your setup).
 
 .. Note::
    It is possible to re-run the ``install`` command. Make
-- 
GitLab