Make docs/README.md compatible with Swift DocC

This adds necessary metadata and updates links to Markdown documents in `README.md`. Remaining `.rst` documents still need to be converted to Markdown for linking to work.

.gitignore

@@ -33,6 +33,7 @@ tags
 #==============================================================================#
 # Generated docs
 docs/_build
+docs/.docc-build
 
 # Finder metadata
 .DS_Store

docs/ABI/GenericSignature.md

@@ -1,8 +1,9 @@
 # Generic Signatures
 
 A generic signature describes a set of generic type parameters along with
-a set of constraints on those parameters. Generic entities in Swift
-have a corresponding generic signature. For example, the following generic function:
+a set of constraints on those parameters.
+
+Generic entities in Swift have a corresponding generic signature. For example, the following generic function:
 
 ```swift
 func foo<C1: Collection, C2: Collection>(c1: C1, c2: C2)

docs/ABI/KeyPaths.md

@@ -2,7 +2,9 @@
 
 **Key path objects** are laid out at runtime as a heap object with a
 variable-sized payload containing a sequence of encoded components describing
-how the key path traverses a value. When the compiler sees a key path literal,
+how the key path traverses a value.
+
+When the compiler sees a key path literal,
 it generates a **key path pattern** that can be efficiently interpreted by
 the runtime to instantiate a key path object when needed. This document
 describes the layout of both. The key path pattern layout is designed in such a

docs/DebuggingTheCompiler.md

@@ -1,7 +1,8 @@
+# Debugging The Compiler
 
-<h1>Debugging The Compiler</h1>
+This document contains some useful information for debugging.
 
-This document contains some useful information for debugging:
+With this document you can learn how to debug:
 
 * The Swift compiler.
 * Intermediate output of the Swift Compiler.
@@ -10,52 +11,6 @@ This document contains some useful information for debugging:
 Please feel free to add any useful tips that one finds to this document for the
 benefit of all Swift developers.
 
-**Table of Contents**
-
-- [Debugging the Compiler Itself](#debugging-the-compiler-itself)
-    - [Basic Utilities](#basic-utilities)
-    - [Printing the Intermediate Representations](#printing-the-intermediate-representations)
-    - [Debugging Diagnostic Emission](#debugging-diagnostic-emission)
-        - [Asserting on first emitted Warning/Assert Diagnostic](#asserting-on-first-emitted-warningassert-diagnostic)
-        - [Finding Diagnostic Names](#finding-diagnostic-names)
-    - [Debugging the Type Checker](#debugging-the-type-checker)
-        - [Enabling Logging](#enabling-logging)
-    - [Debugging on SIL Level](#debugging-on-sil-level)
-        - [Options for Dumping the SIL](#options-for-dumping-the-sil)
-        - [Getting CommandLine for swift stdlib from Ninja to enable dumping stdlib SIL](#getting-commandline-for-swift-stdlib-from-ninja-to-enable-dumping-stdlib-sil)
-        - [Dumping the SIL and other Data in LLDB](#dumping-the-sil-and-other-data-in-lldb)
-    - [Debugging and Profiling on SIL level](#debugging-and-profiling-on-sil-level)
-        - [SIL source level profiling using -sil-based-debuginfo](#sil-source-level-profiling)
-        - [ViewCFG: Regex based CFG Printer for SIL/LLVM-IR](#viewcfg-regex-based-cfg-printer-for-silllvm-ir)
-        - [Debugging the Compiler using advanced LLDB Breakpoints](#debugging-the-compiler-using-advanced-lldb-breakpoints)
-        - [Debugging the Compiler using LLDB Scripts](#debugging-the-compiler-using-lldb-scripts)
-        - [Custom LLDB Commands](#custom-lldb-commands)
-    - [Debugging at LLVM Level](#debugging-at-llvm-level)
-        - [Options for Dumping LLVM IR](#options-for-dumping-llvm-ir)
-    - [Bisecting Compiler Errors](#bisecting-compiler-errors)
-        - [Bisecting on SIL optimizer pass counts to identify optimizer bugs](#bisecting-on-sil-optimizer-pass-counts-to-identify-optimizer-bugs)
-        - [Using git-bisect in the presence of branch forwarding/feature branches](#using-git-bisect-in-the-presence-of-branch-forwardingfeature-branches)
-        - [Reducing SIL test cases using bug_reducer](#reducing-sil-test-cases-using-bug_reducer)
-- [Debugging the Compiler Build](#debugging-the-compiler-build)
-    - [Build Dry Run](#build-dry-run)
-- [Debugging the Compiler Driver](#debugging-the-compiler-driver-build)
-    - [Swift Compiler Driver F.A.Q](#swift-compiler-driver-f.a.q.)
-    - [Building the compiler without using the standalone driver](#building-the-compiler-without-the-standalone-driver)
-    - [Invoking the compiler without forwarding to the standalone driver](#invoking-the-compiler-without-forwarding-to-the-standalone-driver)
-    - [Reproducing the Compiler Driver build steps](#reproducing-the-compiler-driver-build-steps)
-    - [Installing the Compiler Driver](#installing-the-compiler-driver)
-- [Debugging Swift Executables](#debugging-swift-executables)
-    - [Determining the mangled name of a function in LLDB](#determining-the-mangled-name-of-a-function-in-lldb)
-    - [Manually symbolication using LLDB](#manually-symbolication-using-lldb)
-    - [Viewing allocation history, references, and page-level info](#viewing-allocation-history-references-and-page-level-info)
-    - [Printing memory contents](#printing-memory-contents)
-- [Debugging LLDB failures](#debugging-lldb-failures)
-    - ["Types" Log](#types-log)
-    - ["Expression" Log](#expression-log)
-    - [Multiple Logs at a Time](#multiple-logs-at-a-time)
-- [Compiler Tools/Options for Bug Hunting](#compiler-toolsoptions-for-bug-hunting)
-    - [Using `clang-tidy` to run the Static Analyzer](#using-clang-tidy-to-run-the-static-analyzer)
-
 # Debugging the Compiler Itself
 
 ## Basic Utilities

docs/GenericsManifesto.md

@@ -1,3 +1,5 @@
+# Swift Generics Manifesto
+
 (Source: https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160229/011666.html, authored by Douglas Gregor)
 
 ## Introduction

docs/OptimizerDesign.md

@@ -1,13 +1,11 @@
-
-### Design of the Swift optimizer
+# Design of the Swift optimizer
 
 This document describes the design of the Swift Optimizer. It is intended for
 developers who wish to debug, improve or simply understand what the Swift
 optimizer does. Basic familiarity with the Swift programming language and
 knowledge of compiler optimizations is required.
 
-
-### Optimization pipeline overview
+## Optimization pipeline overview
 
 The Swift compiler translates textual Swift programs into LLVM-IR and uses
 multiple representations in between. The Swift frontend is responsible for
@@ -47,7 +45,7 @@ higher-level optimizations. For example, the ARC optimizer and devirtualizer
 need SSA representation to analyze the program, and dead-code-elimination is a
 prerequisite to the array optimizations.
 
-### The Swift Pass Manager
+## The Swift Pass Manager
 
 The Swift pass manager is the unit that executes optimization
 passes on the functions in the Swift module. Unlike the LLVM optimizer, the
@@ -71,7 +69,7 @@ after specific optimizations and to measure how much time is spent in
 each pass.
 
 
-### Optimization passes
+## Optimization passes
 
 There are two kind of optimization passes in Swift: Function passes, and Module
 passes. Function passes can inspect the entire module but can only modify a
@@ -102,7 +100,7 @@ This is the structure of a simple function pass:
 ```
 
 
-### Analysis Invalidation
+## Analysis Invalidation
 
 Swift Analysis are very different from LLVM analysis. Swift analysis are simply
 a cache behind some utility that performs computation. For example, the
@@ -159,7 +157,7 @@ The invalidation traits that passes can invalidate are:
 3. Branches - branches in the code were added, deleted or modified.
 4. Functions - Some functions were added or deleted.
 
-### Semantic Tags
+## Semantic Tags
 
 The Swift optimizer has optimization passes that target specific data structures
 in the Swift standard library. For example, one optimization can remove the
@@ -192,7 +190,7 @@ pipeline.
 Please refer to the document "High-Level SIL Optimizations" for more details.
 
 
-### Instruction Invalidation in SIL
+## Instruction Invalidation in SIL
 
 Swift Passes and Analysis often keep instruction pointers in internal data
 structures such as Map or Set.  A good example of such data structure is a list
@@ -231,14 +229,14 @@ following virtual method:
   }
 ```
 
-### Debugging the optimizer
+## Debugging the optimizer
 
 TODO.
 
-### Whole Module Optimizations
+## Whole Module Optimizations
 
 TODO.
 
-### List of passes
+## List of passes
 
 The updated list of passes is available in the file "Passes.def".