docs: Address quickstart guide issues (#276)

* docs: Address quickstart guide issues

This fixes several user reported issues in the quickstart guide, the big one
being persistent storage of grafana/influxdb data.

See #238 for more details.

* Configure language in Sphinx

* Fix docstring section title

docs/conf.py

@@ -68,7 +68,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/developer/agents.rst

@@ -1,3 +1,5 @@
+.. _agents:
+
 Agents
 ======
 

docs/user/docker_config.rst

@@ -25,7 +25,10 @@ section of this documentation. An example `docker-compose.yaml` file looks
 something like this (note this does not contain all possibly configured
 components)::
 
-    version: '2'
+    version: '3.7'
+    volumes:
+      grafana-storage:
+
     services:
       # --------------------------------------------------------------------------
       # Grafana for the live monitor.
@@ -36,7 +39,7 @@ components)::
         ports:
           - "127.0.0.1:3000:3000"
         volumes:
-          - /srv/grafana:/var/lib/grafana
+          - grafana-storage:/var/lib/grafana
 
       # InfluxDB Backend for Grafana
       influxdb:
@@ -45,6 +48,8 @@ components)::
         restart: always
         ports:
           - "8086:8086"
+        volumes:
+          - /srv/influxdb:/var/lib/influxdb
 
       # --------------------------------------------------------------------------
       # Crossbar
@@ -239,14 +244,16 @@ Where the separate compose files would look something like::
       default:
         external:
           name: ocs-net
+    volumes:
+      grafana-storage:
     services:
       grafana:
         image: grafana/grafana:latest
         restart: always
         ports:
           - "127.0.0.1:3000:3000"
         volumes:
-          - /srv/grafana:/var/lib/grafana
+          - grafana-storage:/var/lib/grafana
 
 ::
 

docs/user/installation.rst

@@ -1,4 +1,4 @@
-.. _installation:
+.. _ocs_install:
 
 Installation
 ============
@@ -8,7 +8,9 @@ Installing Docker
 
 Docker is used to run many of the components in the live monitor. While the
 system can be run without Docker, it is the recommended deployment option. To
-install, please follow the `installation`_ documentation on the Docker website.
+install, please follow the `installation
+<https://docs.docker.com/engine/install/ubuntu/>`_ documentation on the Docker
+website.
 
 .. note::
 
@@ -59,12 +61,12 @@ To install, clone the repository and use pip to install::
 
   git clone https://github.com/simonsobs/ocs.git
   cd ocs/
-  pip3 install -r requirements.txt .
+  pip install -r requirements.txt .
 
 .. note::
 
     If you want to install locally, not globally, throw the `--user` flag
-    on both the pip3 and setup.py commands.
+    when installing with pip.
 
 .. _Docker Compose: https://docs.docker.com/compose/install/
 
@@ -81,15 +83,15 @@ container.
 The OCS user, `ocs`, has a UID of 9000, and a matching group, also called
 `ocs`, with a GID of 9000. To create the group and user run::
 
-    $ groupadd -g 9000 ocs
-    $ useradd -u 9000 -g 9000 ocs
+    $ sudo groupadd -g 9000 ocs
+    $ sudo useradd -u 9000 -g 9000 ocs
 
 Next we need to create the data directory which the aggregator will write files
 to. This can be any directory, for example, ``/data``, which we will use
 throughout this documentation::
 
-    $ mkdir /data
-    $ chown 9000:9000 /data
+    $ sudo mkdir /data
+    $ sudo chown 9000:9000 /data
 
 Finally, we should add the current user account to the `ocs` group, replace
 `user` with your current user::