Cleanup rustdoc chapters a bit

* Rename "The walking tour of rustdoc" to "Rustdoc overview",
  which I think is a more accurate name
* Use same name in sidebar TOC as in chapter text
* Make links between the two chapters prominent
* Convert a few `.html` links to `.md`

Probably we should just merge the chapters, but leaving that for later.

3 files changed, 9 insertions, 12 deletions

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 02e8e3843f3..056ff050f89 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -13,7 +13,7 @@
     - [Suggested Workflows](./building/suggested.md)
     - [Distribution artifacts](./building/build-install-distribution-artifacts.md)
     - [Documenting Compiler](./building/compiler-documenting.md)
-    - [Rustdoc](./rustdoc.md)
+    - [Rustdoc overview](./rustdoc.md)
     - [ctags](./building/ctags.md)
     - [Adding a new target](./building/new-target.md)
 - [The compiler testing framework](./tests/intro.md)
@@ -63,7 +63,7 @@
 - [Memory Management in Rustc](./memory.md)
 - [Serialization in Rustc](./serialization.md)
 - [Parallel Compilation](./parallel-rustc.md)
-- [Rustdoc](./rustdoc-internals.md)
+- [Rustdoc internals](./rustdoc-internals.md)
 
 # Source Code Representation
 
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals.md b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
index 3e950a0eb85..b2dc2f7fd1e 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
@@ -3,7 +3,7 @@
 <!-- toc -->
 
 This page describes rustdoc's passes and modes. For an overview of rustdoc,
-see [`rustdoc`](./rustdoc.md).
+see the ["Rustdoc overview" chapter](./rustdoc.md).
 
 ## From crate to clean
 
diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index c087689d9b4..33f2c5f3571 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -1,17 +1,20 @@
-# The walking tour of rustdoc
+# Rustdoc overview
 
 Rustdoc actually uses the rustc internals directly. It lives in-tree with the
 compiler and standard library. This chapter is about how it works.
 For information about Rustdoc's features and how to use them, see
 the [Rustdoc book](https://doc.rust-lang.org/nightly/rustdoc/).
+For more details about how rustdoc works, see the ["Rustdoc internals" chapter].
+
+["Rustdoc internals" chapter]: ./rustdoc-internals.md
 
 Rustdoc is implemented entirely within the crate [`librustdoc`][rd]. It runs
 the compiler up to the point where we have an internal representation of a
 crate (HIR) and the ability to run some queries about the types of items. [HIR]
 and [queries] are discussed in the linked chapters.
 
-[HIR]: ./hir.html
-[queries]: ./query.html
+[HIR]: ./hir.md
+[queries]: ./query.md
 [rd]: https://github.com/rust-lang/rust/tree/master/src/librustdoc
 
 `librustdoc` performs two major steps after that to render a set of
@@ -59,9 +62,3 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
 * Tests on search index generation are located in `src/test/rustdoc-js`, as a
   series of JavaScript files that encode queries on the standard library search
   index and expected results.
-
-## See also
-
-For more details about how rustdoc works, see the page on [rustdoc internals].
-
-[rustdoc internals]: ./rustdoc-internals.md