Updating docs and adding db

Author: jwbear

docs/troubleshooting.rst

@@ -1,116 +1,131 @@
 Issues & Troubleshooting
 ========================
 
-
-##### MAC OS INSTALLATION ######
-====================
-
+Mac OS Installation
+===================
 
 Docker/Database Issues
 ----------------------
 
 Make sure Docker is installed:
 
 Download the dmg installer from:
-docker: https://docs.docker.com/desktop/setup/install/mac-install/
+https://docs.docker.com/desktop/setup/install/mac-install/
 
-Database: mariadb_config error
-----------------------
-Sometimes the plug in isnt properly set up or can't be found.
+### Database: `mariadb_config` error
+
+Sometimes the plugin isn't properly set up or can't be found.
 
-check:
-which mariadb
+Check:
+
+.. code-block:: bash
+
+   which mariadb
 
 If no path is displayed:
 
-1)
+1. Install the connector:
 
-.. code-block:: bash
-brew install mariadb-connector-c
+   .. code-block:: bash
 
-2) Add missing paths
+      brew install mariadb-connector-c
 
-Add these to path (Intel)
+2. Add missing paths:
+
+**For Intel:**
 
 .. code-block:: bash
-export PATH="/usr/local/opt/mariadb-connector-c/bin:$PATH"
-export CPPFLAGS="-I/usr/local/opt/mariadb-connector-c/include"
-export LDFLAGS="-L/usr/local/opt/mariadb-connector-c/lib"
-MARIADB_CONFIG=/usr/local/opt/mariadb-connector-c/bin/mariadb_config
 
-Add these to path (Silicon)
+   export PATH="/usr/local/opt/mariadb-connector-c/bin:$PATH"
+   export CPPFLAGS="-I/usr/local/opt/mariadb-connector-c/include"
+   export LDFLAGS="-L/usr/local/opt/mariadb-connector-c/lib"
+   export MARIADB_CONFIG=/usr/local/opt/mariadb-connector-c/bin/mariadb_config
+
+**For Apple Silicon:**
 
 .. code-block:: bash
-export PATH="/opt/homebrew/opt/mariadb-connector-c/bin:$PATH"
-export CPPFLAGS="-I/opt/homebrew/opt/mariadb-connector-c/include"
-export LDFLAGS="-L/opt/homebrew/opt/mariadb-connector-c/lib"
-MARIADB_CONFIG=/opt/homebrew/opt/mariadb-connector-c/bin/mariadb_config
 
-3) Manually install mariadb
+   export PATH="/opt/homebrew/opt/mariadb-connector-c/bin:$PATH"
+   export CPPFLAGS="-I/opt/homebrew/opt/mariadb-connector-c/include"
+   export LDFLAGS="-L/opt/homebrew/opt/mariadb-connector-c/lib"
+   export MARIADB_CONFIG=/opt/homebrew/opt/mariadb-connector-c/bin/mariadb_config
 
-.. code-block:: bash
-pip install mariadb
+3. Manually install MariaDB Python bindings:
 
-4) Update shell
+   .. code-block:: bash
 
-.. code-block:: bash
-source ~/.zshrc
+      pip install mariadb
 
+4. Update your shell environment:
 
+   .. code-block:: bash
 
-##### LINUX INSTALLATION ######
-====================
+      source ~/.zshrc
+
+Linux Installation
+==================
 
 Prerequisite Libraries/Plugins
-----------------------
+------------------------------
 
-These are not installed by default so it is helpful to ensure all the python tools are installed:
+These are not installed by default, so it is helpful to ensure all Python tools are available:
 
 .. code-block:: bash
-sudo apt update
-sudo apt install software-properties-common -y
-sudo add-apt-repository ppa:deadsnakes/ppa -y
-sudo apt update
-sudo apt update
-sudo apt install -y python3-dev python3-pip python3-venv build-essential
-sudo apt update
-sudo apt install python3.11 python3.11-venv python3.11-dev -y
-
-GCC
+
+   sudo apt update
+   sudo apt install software-properties-common -y
+   sudo add-apt-repository ppa:deadsnakes/ppa -y
+   sudo apt update
+   sudo apt install -y python3-dev python3-pip python3-venv build-essential
+   sudo apt install python3.11 python3.11-venv python3.11-dev -y
+
+Install GCC:
+
 .. code-block:: bash
-sudo apt install build-essential -y
 
+   sudo apt install build-essential -y
+
+### Database: `mariadb_config` error
 
-Database: mariadb_config error
-----------------------
 .. code-block:: bash
-sudo apt install libmariadb-dev -y
 
-#check
+   sudo apt install libmariadb-dev -y
+
+Check:
+
 .. code-block:: bash
-mariadb_config --cflags
-mariadb_config --libs
+
+   mariadb_config --cflags
+   mariadb_config --libs
 
 Docker Issues
-----------------------
+-------------
+
+After installing Docker, if you get a permissions error when running `dt-db up`:
 
-After installing Docker if there is a permissions error when running dt-db up:
+1.
 
-1)
 .. code-block:: bash
-sudo groupadd docker
 
-2)
+   sudo groupadd docker
+
+2.
+
 .. code-block:: bash
-sudo usermod -aG docker $USER
 
-3)
+   sudo usermod -aG docker $USER
+
+3.
+
 .. code-block:: bash
-newgrp docker
 
-4) Verify:
+   newgrp docker
+
+4. Verify Docker is working:
+
 .. code-block:: bash
-docker ps
+
+   docker ps
 
 ---