6 files changed, 60 insertions, 110 deletions

diff --git a/documentation/toaster-manual/history.rst b/documentation/toaster-manual/history.rst
deleted file mode 100644
index 05b63e5b9a..0000000000
--- a/documentation/toaster-manual/history.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
-
-***********************
-Manual Revision History
-***********************
-
-.. list-table::
-   :widths: 10 15 40
-   :header-rows: 1
-
-   * - Revision
-     - Date
-     - Note
-   * - 1.8
-     - April 2015
-     - The initial document released with the Yocto Project 1.8 Release
-   * - 2.0
-     - October 2015
-     - Released with the Yocto Project 2.0 Release.
-   * - 2.1
-     - April 2016
-     - Released with the Yocto Project 2.1 Release.
-   * - 2.2
-     - October 2016
-     - Released with the Yocto Project 2.2 Release.
-   * - 2.3
-     - May 2017
-     - Released with the Yocto Project 2.3 Release.
-   * - 2.4
-     - October 2017
-     - Released with the Yocto Project 2.4 Release.
-   * - 2.5
-     - May 2018
-     - Released with the Yocto Project 2.5 Release.
-   * - 2.6
-     - November 2018
-     - Released with the Yocto Project 2.6 Release.
-   * - 2.7
-     - May 2019
-     - Released with the Yocto Project 2.7 Release.
-   * - 3.0
-     - October 2019
-     - Released with the Yocto Project 3.0 Release.
-   * - 3.1
-     - April 2020
-     - Released with the Yocto Project 3.1 Release.
diff --git a/documentation/toaster-manual/index.rst b/documentation/toaster-manual/index.rst
index f13ba7b8a1..3ff4c6913a 100644
--- a/documentation/toaster-manual/index.rst
+++ b/documentation/toaster-manual/index.rst
@@ -14,6 +14,5 @@ Toaster User Manual
    start
    setup-and-use
    reference
-   history
 
 .. include:: /boilerplate.rst
diff --git a/documentation/toaster-manual/intro.rst b/documentation/toaster-manual/intro.rst
index 57e5b2bb7b..046ff88ce8 100644
--- a/documentation/toaster-manual/intro.rst
+++ b/documentation/toaster-manual/intro.rst
@@ -76,9 +76,8 @@ extensive information about the build process.
    -  See performance information such as build time, task time, CPU
       usage, and disk I/O.
 
-For an overview of Toaster shipped with the Yocto Project &DISTRO;
-Release, see the "`Toaster - Yocto Project
-2.2 <https://youtu.be/BlXdOYLgPxA>`__" video.
+For an overview of Toaster, see this
+`introduction video <https://youtu.be/BlXdOYLgPxA>`__.
 
 Installation Options
 ====================
@@ -92,6 +91,7 @@ suited for a single user developing on a single build host.
 
 .. image:: figures/simple-configuration.png
    :align: center
+   :width: 70%
 
 Toaster as a hosted service is suited for multiple users developing
 across several build hosts. When Toaster is set up as a hosted service,
@@ -99,3 +99,4 @@ its components can be spread across several machines:
 
 .. image:: figures/hosted-service.png
    :align: center
+   :width: 50%
diff --git a/documentation/toaster-manual/reference.rst b/documentation/toaster-manual/reference.rst
index d2ab14c8e6..755b895cee 100644
--- a/documentation/toaster-manual/reference.rst
+++ b/documentation/toaster-manual/reference.rst
@@ -9,8 +9,8 @@ concepts and have some basic command reference material available. This
 final chapter provides conceptual information on layer sources,
 releases, and JSON configuration files. Also provided is a quick look at
 some useful ``manage.py`` commands that are Toaster-specific.
-Information on ``manage.py`` commands does exist across the Web and the
-information in this manual by no means attempts to provide a command
+Information on ``manage.py`` commands is available across the Web and
+this manual by no means attempts to provide a command
 comprehensive reference.
 
 Layer Source
@@ -28,13 +28,11 @@ at :oe_layerindex:`/`. You can find the code for this
 layer index's web application at :yocto_git:`/layerindex-web/`.
 
 When you tie a layer source into Toaster, it can query the layer source
-through a
-`REST <https://en.wikipedia.org/wiki/Representational_state_transfer>`__
+through a :wikipedia:`REST <Representational_state_transfer>`
 API, store the information about the layers in the Toaster database, and
 then show the information to users. Users are then able to view that
-information and build layers from Toaster itself without worrying about
-cloning or editing the BitBake layers configuration file
-``bblayers.conf``.
+information and build layers from Toaster itself without having to
+clone or edit the BitBake layers configuration file ``bblayers.conf``.
 
 Tying a layer source into Toaster is convenient when you have many
 custom layers that need to be built on a regular basis by a community of
@@ -67,7 +65,7 @@ layers.
 For general information on layers, see the
 ":ref:`overview-manual/yp-intro:the yocto project layer model`"
 section in the Yocto Project Overview and Concepts Manual. For information on how
-to create layers, see the ":ref:`dev-manual/common-tasks:understanding and creating layers`"
+to create layers, see the ":ref:`dev-manual/layers:understanding and creating layers`"
 section in the Yocto Project Development Tasks Manual.
 
 Configuring Toaster to Hook Into Your Layer Index
@@ -187,20 +185,20 @@ Configuring the Workflow
 ------------------------
 
 The ``bldcontrol/management/commands/checksettings.py`` file controls
-workflow configuration. The following steps outline the process to
+workflow configuration. Here is the process to
 initially populate this database.
 
-1. The default project settings are set from
+#. The default project settings are set from
    ``orm/fixtures/settings.xml``.
 
-2. The default project distro and layers are added from
+#. The default project distro and layers are added from
    ``orm/fixtures/poky.xml`` if poky is installed. If poky is not
    installed, they are added from ``orm/fixtures/oe-core.xml``.
 
-3. If the ``orm/fixtures/custom.xml`` file exists, then its values are
+#. If the ``orm/fixtures/custom.xml`` file exists, then its values are
    added.
 
-4. The layer index is then scanned and added to the database.
+#. The layer index is then scanned and added to the database.
 
 Once these steps complete, Toaster is set up and ready to use.
 
@@ -208,7 +206,7 @@ Customizing Pre-Set Data
 ------------------------
 
 The pre-set data for Toaster is easily customizable. You can create the
-``orm/fixtures/custom.xml`` file to customize the values that go into to
+``orm/fixtures/custom.xml`` file to customize the values that go into
 the database. Customization is additive, and can either extend or
 completely replace the existing values.
 
@@ -238,7 +236,7 @@ The following example sets "name" to "CUSTOM_XML_ONLY" and its value to
 Understanding Fixture File Format
 ---------------------------------
 
-The following is an overview of the file format used by the
+Here is an overview of the file format used by the
 ``oe-core.xml``, ``poky.xml``, and ``custom.xml`` files.
 
 The following subsections describe each of the sections in the fixture
@@ -297,7 +295,7 @@ The following defines the releases when you create a new project:
       <field type="CharField" name="description">Yocto Project &DISTRO; "&DISTRO_NAME;"</field>
       <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
       <field type="CharField" name="branch_name">&DISTRO_NAME_NO_CAP;</field>
-      <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP;">Yocto Project &DISTRO_NAME; branch</a>.</field>
+      <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP;">Yocto Project &DISTRO_NAME; branch</a>.</field>
    </object>
 
 The "pk" value must match the above respective BitBake version record.
@@ -334,9 +332,9 @@ that includes the layer. In general all releases include the layer.
       <field type="CharField" name="name">openembedded-core</field>
       <field type="CharField" name="layer_index_url"></field>
       <field type="CharField" name="vcs_url">git://git.yoctoproject.org/poky</field>
-      <field type="CharField" name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field>
-      <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
-      <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
+      <field type="CharField" name="vcs_web_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky</field>
+      <field type="CharField" name="vcs_web_tree_base_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
+      <field type="CharField" name="vcs_web_file_base_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
    </object>
    <object model="orm.layer_version" pk="1">
       <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
@@ -370,8 +368,8 @@ Remote Toaster Monitoring
 Toaster has an API that allows remote management applications to
 directly query the state of the Toaster server and its builds in a
 machine-to-machine manner. This API uses the
-`REST <https://en.wikipedia.org/wiki/Representational_state_transfer>`__
-interface and the transfer of JSON files. For example, you might monitor
+:wikipedia:`REST <Representational_state_transfer>` interface and the
+transfer of JSON files. For example, you might monitor
 a build inside a container through well supported known HTTP ports in
 order to easily access a Toaster server inside the container. In this
 example, when you use this direct JSON API, you avoid having web page
@@ -408,7 +406,7 @@ To get the status of pending builds, use the following call::
 Be sure to provide values for host and port. The output is a JSON file that
 itemizes all builds in progress. This file includes the time in seconds since
 each respective build started as well as the progress of the cloning, parsing,
-and task execution. The following is sample output for a build in progress:
+and task execution. Here is sample output for a build in progress:
 
 .. code-block:: JSON
 
@@ -441,8 +439,8 @@ call::
    http://host:port/toastergui/api/builds
 
 Be sure to provide values for host and port. The output is a JSON file that
-itemizes all complete builds, and includes build summary information. The
-following is sample output for a completed build:
+itemizes all complete builds, and includes build summary information. Here
+is sample output for a completed build:
 
 .. code-block:: JSON
 
@@ -480,7 +478,7 @@ Completed query. See the ":ref:`toaster-manual/reference:checking status of buil
 section for more information.
 
 The output is a JSON file that itemizes the specific build and includes
-build summary information. The following is sample output for a specific
+build summary information. Here is sample output for a specific
 build:
 
 .. code-block:: JSON
@@ -509,7 +507,7 @@ Useful Commands
 ===============
 
 In addition to the web user interface and the scripts that start and
-stop Toaster, command-line commands exist through the ``manage.py``
+stop Toaster, command-line commands are available through the ``manage.py``
 management script. You can find general documentation on ``manage.py``
 at the
 `Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__
@@ -523,14 +521,13 @@ tasks. You can locate these commands in the
 
    -  When using ``manage.py`` commands given a default configuration,
       you must be sure that your working directory is set to the
-      :term:`Build Directory`. Using
-      ``manage.py`` commands from the Build Directory allows Toaster to
-      find the ``toaster.sqlite`` file, which is located in the Build
-      Directory.
+      :term:`Build Directory`. Using ``manage.py`` commands from the
+      :term:`Build Directory` allows Toaster to find the ``toaster.sqlite``
+      file, which is located in the :term:`Build Directory`.
 
    -  For non-default database configurations, it is possible that you
       can use ``manage.py`` commands from a directory other than the
-      Build Directory. To do so, the ``toastermain/settings.py`` file
+      :term:`Build Directory`. To do so, the ``toastermain/settings.py`` file
       must be configured to point to the correct database backend.
 
 ``buildslist``
@@ -550,11 +547,11 @@ database.
 You need to run the ``buildslist`` command first to identify existing
 builds in the database before using the
 :ref:`toaster-manual/reference:\`\`builddelete\`\`` command. Here is an
-example that assumes default repository and build directory names:
+example that assumes default repository and :term:`Build Directory` names:
 
 .. code-block:: shell
 
-   $ cd ~/poky/build
+   $ cd poky/build
    $ python ../bitbake/lib/toaster/manage.py buildslist
 
 If your Toaster database had only one build, the above
diff --git a/documentation/toaster-manual/setup-and-use.rst b/documentation/toaster-manual/setup-and-use.rst
index ded771e796..a0c27499ba 100644
--- a/documentation/toaster-manual/setup-and-use.rst
+++ b/documentation/toaster-manual/setup-and-use.rst
@@ -23,8 +23,8 @@ Once in that directory, source the build environment script::
 
    $ source oe-init-build-env
 
-Next, from the build directory (e.g.
-``poky/build``), start Toaster using this command::
+Next, from the :term:`Build Directory` (e.g. ``poky/build``), start Toaster
+using this command::
 
    $ source toaster start
 
@@ -124,14 +124,14 @@ causes Toaster to create and use ``$TOASTER_DIR./_toaster_clones``.
 The Build Directory
 ===================
 
-Toaster creates a build directory within your Source Directory (e.g.
+Toaster creates a :term:`Build Directory` within your Source Directory (e.g.
 ``poky``) to execute the builds.
 
 Alternatively, if you would like all of your Toaster related files and
 directories to be in a particular location, you can set the
 ``TOASTER_DIR`` environment variable, which takes precedence over your
 current working directory. Setting this environment variable causes
-Toaster to use ``$TOASTER_DIR/build`` as the build directory.
+Toaster to use ``$TOASTER_DIR/build`` as the :term:`Build Directory`.
 
 Creating a Django Superuser
 ===========================
@@ -152,10 +152,10 @@ superuser by following these steps:
       $ export PATH=$PATH:$HOME/.local/bin
 
 #. From the directory containing the Toaster database, which by default
-   is the :term:`Build Directory`,
-   invoke the ``createsuperuser`` command from ``manage.py``::
+   is the :term:`Build Directory`, invoke the ``createsuperuser`` command from
+   ``manage.py``::
 
-      $ cd ~/poky/build
+      $ cd poky/build
       $ ../bitbake/lib/toaster/manage.py createsuperuser
 
 #. Django prompts you for the username, which you need to provide.
@@ -179,7 +179,7 @@ example, if you are running Toaster locally, use the following URL::
    http://127.0.0.1:8000/admin
 
 You can use the Django administration interface to set Toaster configuration
-parameters such as the build directory, layer sources, default variable
+parameters such as the :term:`Build Directory`, layer sources, default variable
 values, and BitBake versions.
 
 Setting Up a Production Instance of Toaster
@@ -211,7 +211,7 @@ Be sure you meet the following requirements:
 
 -  If you are using Ubuntu, run the following::
 
-      $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
+      $ sudo apt install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
 
 -  If you are using Fedora or a RedHat distribution, run the
    following::
@@ -239,7 +239,7 @@ Perform the following steps to install Toaster:
       $ git clone git://git.yoctoproject.org/poky
       $ git checkout &DISTRO_NAME_NO_CAP;
 
-#.  Install Toaster dependencies using the --user flag which keeps the
+#.  Install Toaster dependencies using the ``--user`` flag which keeps the
     Python packages isolated from your system-provided packages::
 
       $ cd /var/www/toaster/
@@ -311,14 +311,13 @@ Perform the following steps to install Toaster:
     migrations). The next line sets the Toaster root directory
     ``TOASTER_DIR`` and the location of the Toaster configuration file
     ``TOASTER_CONF``, which is relative to ``TOASTER_DIR``. The
-    ``TEMPLATECONF`` value reflects the contents of
+    :term:`TEMPLATECONF` value reflects the contents of
     ``poky/.templateconf``, and by default, should include the string
     "poky". For more information on the Toaster configuration file, see
     the ":ref:`toaster-manual/reference:Configuring Toaster`" section.
 
     This line also runs the ``checksettings`` command, which configures
-    the location of the Toaster :term:`Build Directory`.
-    The Toaster
+    the location of the Toaster :term:`Build Directory`. The Toaster
     root directory ``TOASTER_DIR`` determines where the Toaster build
     directory is created on the file system. In the example above,
     ``TOASTER_DIR`` is set as follows::
@@ -326,7 +325,7 @@ Perform the following steps to install Toaster:
        /var/www/toaster/poky
 
 
-    This setting causes the Toaster build directory to be::
+    This setting causes the Toaster :term:`Build Directory` to be::
 
        /var/www/toaster/poky/build
 
@@ -362,11 +361,11 @@ Perform the following steps to install Toaster:
 
       /etc/httpd/conf.d/toaster.conf
 
-    If you are using OpenSUSE, put it here::
+    If you are using openSUSE, put it here::
 
       /etc/apache2/conf.d/toaster.conf
 
-    Following is a sample Apache configuration for Toaster you can follow:
+    Here is a sample Apache configuration for Toaster you can follow:
 
     .. code-block:: apache
 
@@ -380,13 +379,13 @@ Perform the following steps to install Toaster:
             Require all granted
          </IfModule>
       </Directory>
-    
+
       <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain>
          <Files "wsgi.py">
             Require all granted
          </Files>
       </Directory>
-    
+
       WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages
       WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
       <Location />
@@ -402,7 +401,7 @@ Perform the following steps to install Toaster:
       $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
 
     Finally, restart Apache to make sure all new configuration is loaded. For Ubuntu,
-    Debian, and OpenSUSE use::
+    Debian, and openSUSE use::
 
       $ sudo service apache2 restart
 
@@ -417,13 +416,13 @@ Perform the following steps to install Toaster:
 
       [Unit]
       Description=Toaster runbuilds
-      
+
       [Service]
       Type=forking User=toaster
       ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start
       ExecStop=/usr/bin/screen -S runbuilds -X quit
       WorkingDirectory=/var/www/toaster/poky
-      
+
       [Install]
       WantedBy=multi-user.target
 
@@ -433,11 +432,11 @@ Perform the following steps to install Toaster:
     up executable permissions::
 
       #!/bin/bash
-      
+
       #export http_proxy=http://proxy.host.com:8080
       #export https_proxy=http://proxy.host.com:8080
       #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy
-      cd ~/poky/
+      cd poky/
       source ./oe-init-build-env build
       source ../bitbake/bin/toaster $1 noweb
       [ "$1" == 'start' ] && /bin/bash
@@ -496,7 +495,7 @@ The Toaster web interface allows you to do the following:
 Toaster Web Interface Videos
 ----------------------------
 
-Following are several videos that show how to use the Toaster GUI:
+Here are several videos that show how to use the Toaster GUI:
 
 -  *Build Configuration:* This
    `video <https://www.youtube.com/watch?v=qYgDZ8YzV6w>`__ overviews and
@@ -625,7 +624,7 @@ To specify ``bash`` 3.2.48 as the version to build, enter
    :scale: 75%
 
 After clicking the "Add variable" button, the settings for
-``PREFERRED_VERSION`` are added to the bottom of the BitBake variables
+:term:`PREFERRED_VERSION` are added to the bottom of the BitBake variables
 list. With these settings, the OpenEmbedded build system builds the
 desired version of the recipe rather than the default version:
 
diff --git a/documentation/toaster-manual/start.rst b/documentation/toaster-manual/start.rst
index c687a82531..2d6474852a 100644
--- a/documentation/toaster-manual/start.rst
+++ b/documentation/toaster-manual/start.rst
@@ -18,7 +18,7 @@ to run the Yocto Project. To do this, follow the instructions in the
 the Yocto Project Development Tasks Manual. For Ubuntu/Debian, you might
 also need to do an additional install of pip3. ::
 
-   $ sudo apt-get install python3-pip
+   $ sudo apt install python3-pip
 
 Establishing Toaster System Dependencies
 ========================================
@@ -40,7 +40,7 @@ command::
    $ pip3 install --user -r bitbake/toaster-requirements.txt
 
 The previous command installs the necessary Toaster modules into a local
-python 3 cache in your ``$HOME`` directory. The caches is actually
+Python 3 cache in your ``$HOME`` directory. The caches is actually
 located in ``$HOME/.local``. To see what packages have been installed
 into your ``$HOME`` directory, do the following::