[Docs] Update Readme and build instruction docs (microsoft#6185)

This workflow has been around long enough to stop treating it as the
"experimental" workflow and just update the documentation to use it.

We've gotten numerous issues lately related to problems building, so
this will hopefully help.

Fixes: microsoft#5762
Related: microsoft#6151

README.md

@@ -34,58 +34,7 @@ As an example of community contribution, this project can also target the [SPIR-
 
 ## Building Sources
 
-Building DXC requires:
-
-* [Git](http://git-scm.com/downloads).
-* [Python](https://www.python.org/downloads/) - version 3.x is required
-* [CMake](https://cmake.org/download/) - version >= 3.17.2
-    * The bundled version with Visual Studio works for Windows.
-* The C++ 14 compiler and runtime of your choosing.
-    * DXC is known to compile with recent versions of GCC, Clang and MSVC.
-
-Building on windows additionally requires:
-
-* [Visual Studio 2019 or later](https://www.visualstudio.com/downloads) - select the following workloads: 
-    * Universal Windows Platform Development
-    * Desktop Development with C++
-* [Windows SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) - version 10.0.18362.0 or newer
-* [Windows Driver Kit](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) - same version as the SDK
-
-> A new experimental simplified build and test workflow is documented [here](docs/BuildingAndTestingDXC.rst).
-
-
-Before you build, you will need to have some additional software installed. This is the most straightforward path - see [Building Sources](https://github.com/microsoft/DirectXShaderCompiler/wiki/Building-Sources) on the Wiki for more options, including Visual Studio 2015 and Ninja support.
-
-* [Git](http://git-scm.com/downloads).
-* [Python](https://www.python.org/downloads/) - version 3.x is required
-* [Visual Studio 2019](https://www.visualstudio.com/downloads) - select the following workloads: 
-    * Universal Windows Platform Development
-    * Desktop Development with C++
-* [Windows SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) - version 10.0.18362.0 or newer
-* [Windows Driver Kit](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) - same version as the SDK
-
-After cloning the project, you can set up a build environment shortcut by double-clicking the `utils\hct\hctshortcut.js` file. This will create a shortcut on your desktop with a default configuration. If your system doesn't have the requisite association for .js files, this may not work. If so, open a cmd window and invoke: `wscript.exe utils\hct\hctshortcut.js`.
-
-Tests are built using the TAEF framework which is included in the Windows Driver Kit.
-
-To build, run this command on the HLSL Console.
-
-    hctbuild
-
-You can also run tests with this command.
-
-    hcttest
-
-
-To see a list of additional commands available, run `hcthelp`
-
-## Running Tests
-
-To run tests, open the HLSL Console and run this command after a successful build.
-
-    hcttest
-
-Some tests will run shaders and verify their behavior. These tests also involve a driver that can execute these shaders. See the next section on how this should be currently set up.
+See the full documentation for [Building and testing DXC](docs/BuildingAndTestingDXC.rst) for detailed instructions.
 
 ## Running Shaders
 

docs/BuildingAndTestingDXC.rst

@@ -21,6 +21,30 @@ generator. In subsequent sections we will describe workflows using Ninja and
 Visual Studio. The Ninja workflow should also apply to makefile generators with
 minimal adaption.
 
+Prerequisites
+-------------
+
+* [Git](http://git-scm.com/downloads).
+* [Python](https://www.python.org/downloads/) - version 3.x is required
+* [CMake](https://cmake.org/download/) - version >= 3.17.2
+    * The bundled version with Visual Studio works for Windows.
+* The C++ 14 compiler and runtime of your choosing.
+    * DXC is known to compile with recent versions of GCC, Clang and MSVC.
+
+Building on windows additionally requires:
+
+* [Visual Studio 2019 or later](https://www.visualstudio.com/downloads) - select the following workloads: 
+    * Universal Windows Platform Development
+    * Desktop Development with C++
+* [Windows SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) - version 10.0.18362.0 or newer
+* [Windows Driver Kit](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) - same version as the SDK
+
+Note: DXC uses submodules for some external dependencies. You must initialize
+the submodules in order to build DXC:
+
+.. code-block:: sh
+  git submodule update --init --recursive
+
 Basic CMake Usage
 -----------------
 
@@ -149,3 +173,33 @@ four commonly used option prefixes:
   code coverage reports. With this setting enabled the
   ``generate-coverage-report`` target is added to the build which produces a
   static HTML page with code coverage analysis results.
+
+Legacy Windows Build Tooling
+----------------------------
+
+After cloning the project, you can set up a build environment shortcut by
+double-clicking the `utils\hct\hctshortcut.js` file. This will create a shortcut
+on your desktop with a default configuration. If your system doesn't have the
+requisite association for .js files, this may not work. If so, open a cmd window
+and invoke: `wscript.exe utils\hct\hctshortcut.js`.
+
+Tests are built using the TAEF framework which is included in the Windows Driver
+Kit.
+
+To build, run this command on the HLSL Console.
+
+.. code-block:: sh
+
+  hctbuild
+
+You can also run tests with this command.
+
+.. code-block:: sh
+
+  hcttest
+
+Some tests will run shaders and verify their behavior. These tests also involve
+a driver that can execute these shaders. See the next section on how this should
+be currently set up.
+
+To see a list of additional commands available, run `hcthelp`