Small tweaks to platform documentation.

- Point platform rules to the explanatory document which people should have read first.
- Update the left nav to include the word "Toolchains"
- move https://bazel.build/extending/platforms from Design Docs to Concepts

It's not much, but it is a start.

Note to the team: The automatic docs from source system makes this painfully complex. We need a way to generate rule doc from source but keep all the organization of how we group rules under what headings to the framework on the docs serving side.

Next steps:
- Update the platforms page.

RELNOTES: None
PiperOrigin-RevId: 504460917
Change-Id: I0acc1bd9ef8f6381f5c898688dddf328dcf513aa

Author: aiuto

src/main/java/com/google/devtools/build/docgen/templates/be/be-toc.vm

@@ -9,7 +9,15 @@ toc:
     path: /reference/be/make-variables
   - title: Functions
     path: /reference/be/functions
-  - title: Language-specific rules
+  - title: Core rules
+    section:
+#foreach ($ruleFamily in $genericRuleFamilies)
+#if ($ruleFamily.size() > 0)
+    - title: ${ruleFamily.name}
+      path: /reference/be/${ruleFamily.id}
+#end
+#end
+  - title: Language Specific rules
     section:
 #foreach ($ruleFamily in $langSpecificRuleFamilies)
 #if ($ruleFamily.size() > 0)
@@ -53,11 +61,3 @@ toc:
     - title: Scala
       path: https://github.com/bazelbuild/rules_scala
       status: external
-  - title: Language-agnostic rules
-    section:
-#foreach ($ruleFamily in $genericRuleFamilies)
-#if ($ruleFamily.size() > 0)
-    - title: ${ruleFamily.name}
-      path: /reference/be/${ruleFamily.id}
-#end
-#end

src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm

@@ -19,6 +19,12 @@
 
 ${ruleFamily.summary}
 
+<h2>Context</h2>
+This set of rules exist to help model specific hardware platforms you are
+building for and the tools you may use to compile code for those platforms.
+The user should be familiar with the concepts explained
+<a href="//extending/platforms">here</a>.
+
 #if (!$singlePage)
 <h2>Rules</h2>
 <ul>

src/main/java/com/google/devtools/build/lib/rules/ToolchainType.java

@@ -71,7 +71,7 @@ public Metadata getMetadata() {
     }
   }
 }
-/*<!-- #BLAZE_RULE (NAME = toolchain_type, FAMILY = Platform)[GENERIC_RULE] -->
+/*<!-- #BLAZE_RULE (NAME = toolchain_type, FAMILY = Platforms and Toolchains)[GENERIC_RULE] -->
 
 <p>
   This rule defines a new type of toolchain -- a simple target that represents a class of tools that

src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java

@@ -77,7 +77,7 @@ public RuleDefinition.Metadata getMetadata() {
         .build();
   }
 }
-/*<!-- #BLAZE_RULE (NAME = constraint_setting, FAMILY = Platform)[GENERIC_RULE] -->
+/*<!-- #BLAZE_RULE (NAME = constraint_setting, FAMILY = Platforms and Toolchains)[GENERIC_RULE] -->
 
 <p>This rule is used to introduce a new constraint type for which a platform may specify a value.
 For instance, you might define a <code>constraint_setting</code> named "glibc_version" to represent

src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintValueRule.java

@@ -75,7 +75,7 @@ public Metadata getMetadata() {
         .build();
   }
 }
-/*<!-- #BLAZE_RULE (NAME = constraint_value, FAMILY = Platform)[GENERIC_RULE] -->
+/*<!-- #BLAZE_RULE (NAME = constraint_value, FAMILY = Platforms and Toolchains)[GENERIC_RULE] -->
 
 This rule introduces a new value for a given constraint type.
 

src/main/java/com/google/devtools/build/lib/rules/platform/PlatformRule.java

@@ -135,7 +135,7 @@ public Metadata getMetadata() {
         .build();
   }
 }
-/*<!-- #BLAZE_RULE (NAME = platform, FAMILY = Platform)[GENERIC_RULE] -->
+/*<!-- #BLAZE_RULE (NAME = platform, FAMILY = Platforms and Toolchains)[GENERIC_RULE] -->
 
 <p>This rule defines a new platform -- a named collection of constraint choices
 (such as cpu architecture or compiler version) describing an environment in

src/main/java/com/google/devtools/build/lib/rules/platform/ToolchainRule.java

@@ -107,7 +107,7 @@ public RuleDefinition.Metadata getMetadata() {
         .build();
   }
 }
-/*<!-- #BLAZE_RULE (NAME = toolchain, FAMILY = Platform)[GENERIC_RULE] -->
+/*<!-- #BLAZE_RULE (NAME = toolchain, FAMILY = Platforms and Toolchains)[GENERIC_RULE] -->
 
 <p>This rule declares a specific toolchain's type and constraints so that it can be selected
 during toolchain resolution. See the