L2SS-434: Improve post-install, fix pytango reference

docs/source/installation.rst

@@ -44,14 +44,9 @@ If not, you can inspect why with ``docker logs <container>``. Note that the cont
 Post-boot Initialisation
 ---------------------------
 
-The following procedure describes how to initialise the system, which is required after installation and after a system reboot.
+After bootstrapping, and after a reboot, the software and hardware of the station needs to be explicitly initialised. Note that the docker containers do restart automatically at system boot.
 
-The docker containers will automatically restart after a system reboot. But the Linux kernel will lose its required custom settings required by our ELK stack. To reconfigure the kernel parameters, run::
-
-  make start elk-configure-host
-  make restart elk
-
-We can now initialise the station configuration, that is, start all the software devices to control the station hardware, and to initialise the hardware with the configured default settings. Go to http://localhost:8888, start a new *Station Control* notebook, and initiate the software boot sequence::
+The following commands start all the software devices to control the station hardware, and initialise the hardware with the configured default settings. Go to http://localhost:8888, start a new *Station Control* notebook, and initiate the software boot sequence::
 
   # reset our boot device
   boot.off()
@@ -76,3 +71,13 @@ We can now initialise the station configuration, that is, start all the software
     print("Done initialising station.")
   else:
     print(f"Failed to initialise station: {boot.initialisation_status_R}")
+
+ELK
+````
+
+The ELK stack requires some kernel settings to be tuned, before it will start. Although ``make bootstrap`` configures the kernel, these settings will not stick after a reboot. You will need to run either::
+
+  make start elk-configure-host
+  make restart elk
+
+after reboot, or configure your system to set ``sysctl -w vm.max_map_count=262144`` (or higher) as root during boot.

docs/source/interfaces/control.rst

@@ -20,7 +20,9 @@ For example, you can start a new *Station Control* notebook (File->New Notebook-
 
 .. image:: jupyter_basic_example.png
 
-Python
+.. _pytango-section:
+
+PyTango
 ------------------------
 
 To access a station from scratch using Python, we need to install some dependencies::

docs/source/interfaces/overview.rst

@@ -15,21 +15,21 @@ The station provides the following interfaces accessible through your browser (a
 
 Futhermore, there are some low-level interfaces:
 
-+---------------------+--------------+----------------------+-------------------+
++---------------------------+--------------+-----------------------+-------------------+
 |Interface                  |Subsystem     |URL                    |Default credentials|
-+=====================+==============+======================+===================+
-|Tango API            |Tango         |http://localhost:10000|                   |
-+---------------------+--------------+----------------------+-------------------+
-|Timeseries Database  |Prometheus    |http://localhost:9090 |                   |
-+---------------------+--------------+----------------------+-------------------+
++===========================+==============+=======================+===================+
+| :ref:`pytango-section`    |Tango         |tango://localhost:10000|                   |
++---------------------------+--------------+-----------------------+-------------------+
+| :ref:`prometheus-section` |Prometheus    |http://localhost:9090  |                   |
++---------------------------+--------------+-----------------------+-------------------+
 | :ref:`rest-api`           |tango-rest    |http://localhost:8080  |tango-cs/tango     |
-+---------------------+--------------+----------------------+-------------------+
++---------------------------+--------------+-----------------------+-------------------+
 | :ref:`tangodb`            |MariaDB       |http://localhost:3306  |tango/tango        |
-+---------------------+--------------+----------------------+-------------------+
++---------------------------+--------------+-----------------------+-------------------+
 |Archive Database           |MariaDB       |http://localhost:3307  |tango/tango        |
-+---------------------+--------------+----------------------+-------------------+
++---------------------------+--------------+-----------------------+-------------------+
 |Log Database               |ElasticSearch |http://localhost:9200  |                   |
-+---------------------+--------------+----------------------+-------------------+
++---------------------------+--------------+-----------------------+-------------------+
 
 .. toctree::
    :hidden: