[Gardening] De-RST DriverInternals

Author: CodaFi

docs/CompilerPerformance.md

@@ -83,7 +83,7 @@ The set of jobs that are run, and the way they spend their time, is itself
 highly dependent on **compilation modes**. Information concerning those modes
 that's relevant to compilation performance is recounted in the following
 section; for more details on the driver, see [the driver docs](Driver.md), as
-well as docs on [driver internals](DriverInternals.rst)
+well as docs on [driver internals](DriverInternals.md)
 and [driver parseable output](DriverParseableOutput.rst).
 
 After discussing compilation modes in the following section, we'll also touch on

docs/Driver.md

@@ -14,7 +14,7 @@ The target audience for this document is people who want to integrate the Swift
 compiler into their build system, rather than using Xcode or the package
 manager (`swift build`). If you're looking to work on the driver itself...well,
 this is probably still useful to you, but you should also check out
-[DriverInternals.rst](DriverInternals.rst) and maybe
+[DriverInternals.md](DriverInternals.md) and maybe
 [DependencyAnalysis.md](DependencyAnalysis.md) as well. If you're just using
 Xcode or SwiftPM and want to find out what mysterious command-line options you
 could be passing, `swiftc --help` is a better choice.

docs/DriverInternals.rst renamed to docs/DriverInternals.md

@@ -1,10 +1,6 @@
-=========================
 Driver Design & Internals
 =========================
 
-.. contents::
-   :local:
-
 Introduction
 ============
 
@@ -24,23 +20,22 @@ Driver Stages
 The compiler driver for Swift roughly follows the same design as Clang's
 compiler driver:
 
-1. Parse: Command-line arguments are parsed into ``Arg``\ s. A ToolChain is
+1. Parse: Command-line arguments are parsed into `Arg`s. A ToolChain is
    selected based on the current platform.
-2. Pipeline: Based on the arguments and inputs, a tree of ``Action``\ s is
+2. Pipeline: Based on the arguments and inputs, a tree of `Action`s is
    generated. These are the high-level processing steps that need to occur,
    such as "compile this file" or "link the output of all compilation actions".
-3. Bind: The ToolChain converts the ``Action``\ s into a set of ``Job``\ s.
+3. Bind: The ToolChain converts the `Action`s into a set of `Job`s.
    These are individual commands that need to be run, such as
    "ld main.o -o main". Jobs have dependencies, but are not organized into a
    tree structure.
-4. Execute: The ``Job``\ s are run in a ``Compilation``, which spawns off
-   sub-processes for each job that needs execution. The ``Compilation`` is
-   responsible for deciding which ``Job``\ s actually need to run, based on
+4. Execute: The `Job`s are run in a `Compilation`, which spawns off
+   sub-processes for each job that needs execution. The `Compilation` is
+   responsible for deciding which `Job`s actually need to run, based on
    dependency information provided by the output of each sub-process. The
-   low-level management of sub-processes is handled by a ``TaskQueue``.
+   low-level management of sub-processes is handled by a `TaskQueue`.
 
-Parse: Option parsing
-^^^^^^^^^^^^^^^^^^^^^
+## Parse: Option parsing
 
 The command line arguments are parsed as options and inputs into Arg instances.
 Some miscellaneous validation and normalization is performed. Most of the
@@ -56,29 +51,22 @@ files. The output file map uses a simple JSON format mapping inputs to a map of
 output paths, keyed by file type. Entries under an input of "" refer to the
 top-level driver process.
 
-.. admonition:: FIXME
-
-    Certain capabilities, like incremental builds or compilation without
-    linking, currently require an output file map. This should not be necessary.
+> Certain capabilities, like incremental builds or compilation without
+> linking, currently require an output file map. This should not be necessary.
 
 
-Pipeline: Converting Args into Actions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Pipeline: Converting Args into Actions
 
 At this stage, the driver will take the input Args and input files and
 establish a graph of Actions. This details the high-level tasks that need to be
 performed. The graph (a DAG) tracks dependencies between actions, but also
 manages ownership.
 
-.. admonition:: FIXME
-
-    Actions currently map one-to-one to sub-process invocations. This means
-    that there are actions for things that should be implementation details,
-    like generating dSYM output.
-
+> Actions currently map one-to-one to sub-process invocations. This means
+> that there are actions for things that should be implementation details,
+> like generating dSYM output.
 
-Build: Translating Actions into Jobs using a ToolChain
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Build: Translating Actions into Jobs using a ToolChain
 
 Once we have a graph of high-level Actions, we need to translate that into
 actual tasks to execute. This starts by determining the output that each Action
@@ -94,8 +82,7 @@ in the current build. This is covered by checking if the input has been
 modified since the last build; if it hasn't, we only need to recompile if
 something it depends on has changed.
 
-Schedule: Ordering and skipping jobs by dependency analysis
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Schedule: Ordering and skipping jobs by dependency analysis
 
 A Compilation's goal is to make sure every Job in its list of Jobs is handled.
 If a Job needs to be run, the Compilation attempts to *schedule* it. If the
@@ -107,11 +94,10 @@ be run, the Compilation keeps track of a DependencyGraph. (If file A depends on
 file B and file B has changed, file A needs to be recompiled.) When a Job
 completes successfully, the Compilation will both re-attempt to schedule Jobs
 that were directly blocked on it, and check to see if any other Jobs now need
-to run based on the DependencyGraph. See the section on :doc:`DependencyAnalysis`
-for more information.
+to run based on the DependencyGraph. See the section on
+[DependencyAnalysis](DependencyAnalysis.md) for more information.
 
-Batch: Optionally combine similar jobs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Batch: Optionally combine similar jobs
 
 The Driver has an experimental "batch mode" that examines the set of scheduled
 jobs just prior to execution, looking for jobs that are identical to one another
@@ -123,8 +109,7 @@ that run (and thus do potentially redundant work).
 Once any batching has taken place, the set of scheduled jobs (batched or
 otherwise) is transferred to the TaskQueue for execution.
 
-Execute: Running the Jobs in a Compilation using a TaskQueue
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Execute: Running the Jobs in a Compilation using a TaskQueue
 
 The Compilation's TaskQueue controls the low-level aspects of managing
 subprocesses. Multiple Jobs may execute simultaneously, but communication with

docs/contents.rst

@@ -8,7 +8,6 @@ Contents
 
    IndexInvalidation
    AccessControl
-   DriverInternals
    DriverParseableOutput
    ErrorHandling
    ErrorHandlingRationale