[trafficcontrol] 18/39: formatting and consistency

[mi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git

commit d0d77402aeea11fcce213cca2dd2456cd16b41c7
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Thu Sep 20 06:12:00 2018 -0600

    formatting and consistency
---
 docs/source/development/building.rst | 96 ++++++++++++------------------------
 1 file changed, 31 insertions(+), 65 deletions(-)

diff --git a/docs/source/development/building.rst b/docs/source/development/building.rst
index f74b4a1..4d20ddd 100644
--- a/docs/source/development/building.rst
+++ b/docs/source/development/building.rst
@@ -1,94 +1,60 @@
-.. 
-.. 
+..
+..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
 .. You may obtain a copy of the License at
-.. 
+..
 ..     http://www.apache.org/licenses/LICENSE-2.0
-.. 
+..
 .. Unless required by applicable law or agreed to in writing, software
 .. distributed under the License is distributed on an "AS IS" BASIS,
 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
-.. 
+..
 
 .. _dev-building:
 
+************************
 Building Traffic Control
-========================
+************************
+The build steps for Traffic Control components are all pretty much the same, despite that they are written in a variety of different languages and frameworks. This is accomplished by using Docker.
 
+.. note:: Currently, both listed methods of building Traffic Control components will produce ``*.rpm`` files, meaning that the support of these components is limited to RedHat-based distributions - and none of them are currently tested (or guaranteed to work) outside of CentOS7, specifically.
 
-Build using pkg
----------------
-
-This is the easiest way to build all the components of Traffic Control;
-all requirements are automatically loaded into the image used to build
-each component.
+Build using ``pkg``
+===================
+This is the easiest way to build all the components of Traffic Control; all requirements are automatically loaded into the image used to build each component.
 
 Requirements
-~~~~~~~~~~~~
-
+------------
 -  ``docker`` (https://docs.docker.com/engine/installation/)
 -  ``docker-compose`` (https://docs.docker.com/compose/install/)
    (optional, but recommended)
 
-If ``docker-compose`` is not available, the ``pkg`` script will
-automatically download and run it in a container. This is noticeably
-slower than running it natively.
+If ``docker-compose`` is not available, the ``pkg`` script will automatically download and run it in a container. This is noticeably slower than running it natively.
 
 Usage
-~~~~~
-
-::
-
-    $ ./pkg -?
-    Usage: ./pkg [options] [projects]
-        -q      Quiet mode. Supresses output.
-        -v      Verbose mode. Lists all build output.
-        -l      List available projects.
-
-        If no projects are listed, all projects will be packaged.
-        Valid projects:
-                - traffic_portal_build
-                - traffic_router_build
-                - traffic_monitor_build
-                - source
-                - traffic_ops_build
-                - traffic_stats_build
-
+-----
+``./pkg [options] [projects]``
 
-If any project names are provided on the command line, only those will be built.
-Otherwise, all projects are built.
+Options:
 
-All artifacts (rpms, logs, source tar ball) are copied to ``dist`` at the top level of the
-``trafficcontrol`` directory.
+-q      Quiet mode. Suppresses output.
+-v      Verbose mode. Lists all build output.
+-l      List available projects.
 
-Example
-~~~~~~~
+If the ``projects`` argument is given, it should be one or more project names. If it is not given, all projects will be built. Valid projects:
 
-::
-
-    $ ./pkg -v source traffic_ops_build
-    Building source.
-    Building traffic_ops_build.
-
-Build using docker-compose
---------------------------
-
-If the ``pkg`` script fails, ``docker-compose`` can still be used directly.
-
-Usage
-~~~~~
+- traffic_portal_build
+- traffic_router_build
+- traffic_monitor_build
+- source
+- traffic_ops_build
+- traffic_stats_build
 
-::
+Output ``*.rpm`` files, build logs and source tarballs will be output to the ``dist`` directory at the root of the Traffic Control repository directory.
 
-    $ docker-compose -f ./infrastructure/docker/build/docker-compose.yml down -v
-    $ docker-compose -f ./infrastructure/docker/build/docker-compose.yml up --build source traffic_ops_build
-    $ ls -1 dist/
-    build-traffic_ops.log
-    traffic_ops-2.1.0-6396.07033d6d.el7.src.rpm
-    traffic_ops-2.1.0-6396.07033d6d.el7.x86_64.rpm
-    traffic_ops_ort-2.1.0-6396.07033d6d.el7.src.rpm
-    traffic_ops_ort-2.1.0-6396.07033d6d.el7.x86_64.rpm
-    apache-trafficcontrol-2.1.0.tar.gz
+Build Using ``docker-compose``
+==============================
+If the ``pkg`` script fails, ``docker-compose`` can still be used to build the projects directly. The compose file can be found at ``infrastructure/docker/build/docker-compose.yml`` under the repository's root directory. It is recommended that between builds ``docker-compose down -v`` is run to prevent caching of old build steps. The service names are the same as the project names described above in `Usage`_, and similar to the ``pkg`` script, the build results, logs and source tarballs  [...]