Clarify DB URI docs, and fix display of --flags that render as -flags…

… in docs (em-dash) (#476)

* Clarify DB URI docs, and fix display of --flags that render as -flags in docs (em-dash)

* Update sqlalchemy remark per review

docs/deployment.rst

@@ -144,9 +144,10 @@ by running:
 
 which starts a web application instance on `http://127.0.0.1:7000` with the
 default (insecure) options. The command line also supports some high-level
-options, such as `--port` and `--dburi` which respectively change the local
-port on which the server is running, and the sqlalchemy uri where the database
-can be found and/or initiated.
+options, such as :code:`--port` and :code:`--dburi` which respectively change the local
+port on which the server is running, and the SQLAlchemy URI of the database to use
+and/or initialize for the post index (which is distinct from the database, if any,
+used to store knowledge posts).
 
 For shared deployments, however, you will probably need to create a server
 configuration file. A complete server configuration template can be found
@@ -163,11 +164,12 @@ provided in the template, deploying the web application is as simple as:
 
   $ knowledge_repo --repo <repo_path> deploy --config <config_file>
 
-Supported options are `--port`, `--dburi`,`--workers`, `--timeout` and
-`--config`. The `--config` option allows you to specify a python config file
-from which to load the extended configuration. A template config file is
-provided in `knowledge_repo/app/config_defaults.py`. The `--port` and `--dburi`
-options are as before, with the `--workers` and `--timeout` options specifying
+Supported options are :code:`--port`, :code:`--dburi`, :code:`--workers`,
+:code:`--timeout` and :code:`--config`. The :code:`--config` option allows you
+to specify a python config file from which to load the extended configuration.
+A template config file is provided in `knowledge_repo/app/config_defaults.py`.
+The :code:`--port` and :code:`--dburi` options are as before, with the
+:code:`--workers` and :code:`--timeout` options specifying
 the number of threads to use when serving through gunicorn, and the timeout
 after which the threads are presumed to have died, and will be restarted.
 
@@ -178,9 +180,13 @@ No matter which knowledge repository backends are used, the web application
 itself requires a database backend in order to store its cache of the post
 index and user permissions. The database to be used can be specified via the
 CLI using the :code:`--dburi` option or via the config file passed in using
-:code:`--config`. Most datatabase backends supported by SQLAlchemy should work.
+:code:`--config`. Most database backends supported by SQLAlchemy should work.
 Database URIs will look something like:
-:code:`mysql://username:password@hostname/database:table_name`.
+:code:`mysql://username:password@hostname/database`.
+
+Note that it's also possible to use a SQLite database backed by a local
+file, or development or simple deployments. Use a URI like
+:code:`sqlite:///my-database.db` or :code:`sqlite:////path/to/my-database.db`.
 
 If the database does not exist, it is created (if that is possible) and
 initialised. When updates to the Knowledge Repo require changes to the database

docs/quickstart.rst

@@ -84,7 +84,7 @@ one way. For more workflows, refer to: :doc:`workflows/writing`.
     $ knowledge_repo --repo <path/uri_of_repo> add example_post.ipynb -p project/example_ipynb
     $ knowledge_repo --repo <path/uri_of_repo> add example_post.Rmd -p project/example_rmd
 
-  Note that the `-p` option specifies the path in the repository to which the post
+  Note that the :code:`-p` option specifies the path in the repository to which the post
   should be added.
 
 .. topic:: Step 6: Preview the added post

docs/workflows/writing.rst

@@ -53,7 +53,7 @@ will create a file, `~/Documents/my_first_knowledge_post.md`, the contents of
 which will be the boilerplate template of the knowledge post.
 
 The help menu for this command (and all following commands) can be reached by
-adding the `-h` flag, `knowledge_repo --repo <repo_path> create -h`.
+adding the :code:`-h` flag, `knowledge_repo --repo <repo_path> create -h`.
 
 Alternatively, by going to the `/create` route in the webapp, you can click the
 button for whichever template you would like to have, and that will download the
@@ -100,15 +100,15 @@ Using the example from above, if we wanted to add the post
   $ knowledge_repo --repo knowledge_data_repo add ~/Documents/my_first_knowledge_post.md -p projects/test_knowledge
 
 
-The `-p` flag specifies the location of the post in the knowledge data
+The :code:`-p` flag specifies the location of the post in the knowledge data
 repository - in this case, `knowledge_data_repo/projects/test_knowledge`. The
-`-p` flag does not need to be specified if `path` is included in the header of
+:code:`-p` flag does not need to be specified if `path` is included in the header of
 the knowledge post.
 
 Updating
 ^^^^^^^^
 
-To update an existing knowledge post, pass the `--update` flag to the `add`
+To update an existing knowledge post, pass the :code:`--update` flag to the `add`
 command. This will allow the add operation to override exiting knowledge posts.
 
 .. code-block:: shell
@@ -132,7 +132,7 @@ In the case from above, we would run:
 
   $ knowledge_repo --repo knowledge_data_repo preview projects/test_knowledge
 
-There are other arguments that can be passed to this command, adding the `-h`
+There are other arguments that can be passed to this command, adding the :code:`-h`
 flag shows them all along with further information about them.
 
 Submitting