Split off troubleshooting section into a FAQ page

Rewrite/add to the contents of this section.

Also updated the page titles / navbar entries of Skylark documentation to make them more uniform (title case, avoid redundancy).

RELNOTES: None
PiperOrigin-RevId: 189503729

14 files changed, 115 insertions, 62 deletions

diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 3726854c0d..63997743a8 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -62,7 +62,7 @@ nav: docs
                    <li><a href="/versions/{{ site.version }}/tutorial/android-app.html">Building an Android App</a></li>
                    <li><a href="/versions/{{ site.version }}/tutorial/ios-app.html">Building an iOS App</a></li>
                    <li><a href="/versions/{{ site.version }}/skylark/tutorial-sharing-variables.html">Sharing Variables</a></li>
-                   <li><a href="/versions/{{ site.version }}/skylark/tutorial-creating-a-macro.html">Creating Macros</a></li>
+                   <li><a href="/versions/{{ site.version }}/skylark/tutorial-creating-a-macro.html">Creating a Macro</a></li>
                  </ul>
               </li>
 
@@ -173,7 +173,7 @@ nav: docs
                     </ul></li>
                </ul></li>
 
-             <li><a href="/versions/{{ site.version }}/skylark/build-style.html">BUILD File Reference</a></li>
+             <li><a href="/versions/{{ site.version }}/skylark/build-style.html">BUILD Style Guide</a></li>
              <li><a href="/versions/{{ site.version }}/command-line-reference.html">Command Line Reference</a></li>
              <li><a href="/versions/{{ site.version }}/build-event-protocol.html">Build Event Protocol</a></li>
              <li><a href="/versions/{{ site.version }}/query.html">Bazel Query Language</a></li>
@@ -184,7 +184,7 @@ nav: docs
 
             <h3>Extending Bazel</h3>
            <ul class="sidebar-nav">
-              <li><a href="/versions/{{ site.version }}/skylark/concepts.html">Overview</a></li>
+              <li><a href="/versions/{{ site.version }}/skylark/concepts.html">Skylark Overview</a></li>
 
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
@@ -198,6 +198,7 @@ nav: docs
                   <li><a href="/versions/{{ site.version }}/skylark/depsets.html">Depsets</a></li>
                   <li><a href="/versions/{{ site.version }}/skylark/aspects.html">Aspects</a></li>
                   <li><a href="/versions/{{ site.version }}/skylark/repository_rules.html">Repository Rules</a></li>
+                  <li><a href="/versions/{{ site.version }}/skylark/faq.html">FAQ</a></li>
                 </ul>
               </li>
 
@@ -208,7 +209,7 @@ nav: docs
                   Best Practices<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="skylark-practices">
-                  <li><a href="/versions/{{ site.version }}/skylark/bzl-style.html">Readability Guidelines</a></li>
+                  <li><a href="/versions/{{ site.version }}/skylark/bzl-style.html">.bzl Style Guide</a></li>
                   <li><a href="/versions/{{ site.version }}/skylark/backward-compatibility.html">Backward Compatibility</a></li>
                   <li><a href="https://skydoc.bazel.build" target="_blank">Documenting Rules</a></li>
                   <li><a href="/versions/{{ site.version }}/skylark/skylint.html">Linter</a></li>
@@ -219,7 +220,7 @@ nav: docs
 
               <li><a href="https://github.com/bazelbuild/examples/tree/master/rules">Examples</a></li>
               <li><a href="/versions/{{ site.version }}/skylark/lib/skylark-overview.html">API Reference</a></li>
-              <li><a href="/versions/{{ site.version }}/skylark/language.html">Skylark Language Reference</a></li>
+              <li><a href="/versions/{{ site.version }}/skylark/language.html">Skylark Language</a></li>
             </ul>
           </nav>
         </div>
diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md
index af77a10908..28057bb179 100644
--- a/site/docs/skylark/backward-compatibility.md
+++ b/site/docs/skylark/backward-compatibility.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Extensions - Backward compatibility
+title: Backward Compatibility
 ---
 
-# Backward compatibility
+# Backward Compatibility
 
 Bazel is still in Beta and new releases may include backward incompatible
 changes. As we make changes and polish the extension mechanism, old features
diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
index 6440fd3ee7..c48484a4d6 100644
--- a/site/docs/skylark/build-style.md
+++ b/site/docs/skylark/build-style.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Style guide for BUILD files
+title: BUILD Style Guide
 ---
 
-# BUILD file style guide
+# BUILD Style Guide
 
 
 In `BUILD` files, we take the same approach as in Go: We let the machine take care
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md
index 552d02280b..6575de34cf 100644
--- a/site/docs/skylark/bzl-style.md
+++ b/site/docs/skylark/bzl-style.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Style guide for bzl files
+title: .bzl Style Guide
 ---
 
-# .bzl file style guide
+# .bzl Style Guide
 
 
 Skylark is a language that defines how software is built, and as such it is both
diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md
index b7cda3433b..2ff2378352 100644
--- a/site/docs/skylark/concepts.md
+++ b/site/docs/skylark/concepts.md
@@ -1,15 +1,15 @@
 ---
 layout: documentation
-title: Extensions - Overview
+title: Skylark Overview
 ---
 
-# Overview
+# Skylark Overview
 
 <!-- [TOC] -->
 
 ## Loading an extension
 
-Extensions are files with the `.bzl` extension. Use the `load` statement to
+Skylark extensions are files ending in `.bzl`. Use the `load` statement to
 import a symbol from an extension.
 
 ```python
diff --git a/site/docs/skylark/cookbook.md b/site/docs/skylark/cookbook.md
index 11cae9a9fa..c5231b8c6b 100644
--- a/site/docs/skylark/cookbook.md
+++ b/site/docs/skylark/cookbook.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Extensions examples
+title: Skylark Examples
 ---
 
-# Extensions examples
+# Skylark Examples
 
 **Tip:** For further examples, see the [GitHub repository](https://github.com/bazelbuild/examples/tree/master/rules).
 
diff --git a/site/docs/skylark/deploying.md b/site/docs/skylark/deploying.md
index 21a80f8b91..b1ae13d8b9 100644
--- a/site/docs/skylark/deploying.md
+++ b/site/docs/skylark/deploying.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Deploying new Skylark rules
+title: Deploying Rules
 ---
 
-# Deploying new rules
+# Deploying Rules
 
 This documentation is for rule writers who are planning to make their
 rules available to others.
diff --git a/site/docs/skylark/faq.md b/site/docs/skylark/faq.md
new file mode 100644
index 0000000000..a39e604350
--- /dev/null
+++ b/site/docs/skylark/faq.md
@@ -0,0 +1,84 @@
+---
+layout: documentation
+title: Skylark FAQ
+---
+
+# Frequently Asked Questions
+
+These are some common issues and questions with writing using Skylark.
+
+<!-- [TOC] -->
+
+
+## Why is my file not produced / my action never executed?
+
+Bazel only executes the actions needed to produce the *requested* output files.
+
+* If the file you want has a label, you can request it directly:
+  `bazel build //pkg:myfile.txt`
+
+* If the file is in an output group of the target, you may need to specify that
+  output group on the command line:
+  `bazel build //pkg:mytarget --output_groups=foo`
+
+* If you want the file to be built automatically whenever your target is
+  mentioned on the command line, add it to your rule's default outputs by
+  returning a [`DefaultInfo`](lib/globals.html#DefaultInfo) provider.
+
+See the [Rules page](rules.md#requesting-output-files) for more information.
+
+## Why is my implementation function not executed?
+
+Bazel analyzes only the targets that are requested for the build. You should
+either name the target on the command line, or something that depends on the
+target.
+
+## A file is missing when my action or binary is executed
+
+Make sure that 1) the file has been registered as an input to the action or
+binary, and 2) the script or tool being executed is accessing the file using the
+correct path.
+
+For actions, you declare inputs by passing them to the `ctx.actions.*` function
+that creates the action. The proper path for the file can be obtained using
+[`File.path`](lib/File.html#path).
+
+For binaries (the executable outputs run by a `bazel run` or `bazel test`
+command), you declare inputs by including them in the
+[runfiles](rules.md#runfiles). Instead of using the `path` field, use
+[`File.short_path`](lib/File.html#short_path), which is file's path relative to
+the runfiles directory in which the binary executes.
+
+## How can I control which files are built by `bazel build //pkg:mytarget`?
+
+Use the [`DefaultInfo`](lib/globals.html#DefaultInfo) provider to
+[set the default outputs](rules.md#requesting-output-files).
+
+## How can I run a program or do file I/O as part of my build?
+
+A tool can be declared as a target, just like any other part of your build, and
+run during the execution phase to help build other targets. To create an action
+that runs a tool, use [`ctx.actions.run`](lib/actions.html#run) and pass in the
+tool as the `executable` parameter.
+
+During the loading and analysis phases, a tool *cannot* run, nor can you perform
+file I/O. This means that tools and file contents (except the contents of BUILD
+and .bzl files) cannot affect how the target and action graphs get created.
+
+## What if I need to access the same structured data both before and during the execution phase?
+
+You can format the structured data as a .bzl file. You can `load()` the file to
+access it during the loading and analysis phases. You can pass it as an input or
+runfile to actions and executables that need it during the execution phase.
+
+## How should I document Skylark code?
+
+For rules and rule attributes, you can pass a docstring literal (possibly
+triple-quoted) to the `doc` parameter of `rule` or `attr.*()`. For helper
+functions and macros, use a triple-quoted docstring literal following the format
+given [here](skylint.md#docstings). Rule implementation functions generally do
+not need their own docstring.
+
+Using string literals in the expected places makes it easier for automated
+tooling to extract documentation. Feel free to use standard non-string comments
+wherever it may help the reader of your code.
diff --git a/site/docs/skylark/language.md b/site/docs/skylark/language.md
index 714254037b..317c8900e8 100644
--- a/site/docs/skylark/language.md
+++ b/site/docs/skylark/language.md
@@ -1,15 +1,15 @@
 ---
 layout: documentation
-title: Extensions - Overview
+title: Skylark Language
 ---
 
-# Language
+# Skylark Language
 
 <!-- [TOC] -->
 
 The page is an overview of Skylark, the language used in Bazel. This should be
 enough to get you started, but you may be interested in a more complete
-[specification of Skylark](spec.md). For a complete list of functions and
+[Skylark Language Specification](spec.md). For a complete list of functions and
 types, please check the [API reference](lib/skylark-overview.html).
 
 ## Syntax
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index ed25ec9136..0a7ae974ce 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -681,35 +681,3 @@ _example_test = rule(
  ...
 )
 ```
-
-## Troubleshooting
-
-### Why is the action never executed?
-
-Bazel executes an action only when at least one of its outputs are requested. If
-the target is built directly, make sure the output you need is in the [default
-outputs](#requesting-output-files).
-
-When the target is used as a dependency, check which providers are used and consumed.
-
-### Why is the implementation function not executed?
-
-Bazel analyzes only the targets that are requested for the build. You should
-either build the target, or build something that depends on the target.
-
-### A file is missing during execution
-
-When you create an action, you need to specify all the inputs. Please
-double-check that you didn't forget anything.
-
-If a binary requires files at runtime, such as dynamic libraries or data files,
-you may need to [specify the runfiles](#runfiles).
-
-### How to choose which files are shown in the output of `bazel build`?
-
-Use the [`DefaultInfo`](lib/globals.html#DefaultInfo) provider to
-[set the default outputs](#requesting-output-files).
-
-### How to run a program in the analysis phase?
-
-It is not possible.
diff --git a/site/docs/skylark/skylint.md b/site/docs/skylark/skylint.md
index 22a235a61f..8a18cfa599 100644
--- a/site/docs/skylark/skylint.md
+++ b/site/docs/skylark/skylint.md
@@ -1,13 +1,13 @@
 ---
 layout: documentation
-title: Skylark Linter Documentation
+title: Skylint
 ---
 
-# Skylark Linter Documentation
+# Skylint
 
 [Style guide](https://docs.bazel.build/versions/master/skylark/bzl-style.html)
 
-This document explains how to use the Skylark linter.
+This document explains how to use Skylint, the Skylark linter.
 
 <!-- [TOC] -->
 
diff --git a/site/docs/skylark/spec.md b/site/docs/skylark/spec.md
index 54c26977e6..197eb8565d 100644
--- a/site/docs/skylark/spec.md
+++ b/site/docs/skylark/spec.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Extensions - Language definition
+title: Skylark Language Specification
 ---
 
-# Skylark: Language definition
+# Skylark Language Specification
 
 Skylark is a dialect of Python intended for use as a configuration
 language.  A Skylark interpreter is typically embedded within a larger
diff --git a/site/docs/skylark/tutorial-creating-a-macro.md b/site/docs/skylark/tutorial-creating-a-macro.md
index 44359907dd..cc75bf57ef 100644
--- a/site/docs/skylark/tutorial-creating-a-macro.md
+++ b/site/docs/skylark/tutorial-creating-a-macro.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Creating a macro
+title: Creating a Macro
 ---
 
-# Creating a macro
+# Creating a Macro
 
 Let's suppose you need to run a tool as part of your build. For example, you
 may want to generate or preprocess a source file, or compress a binary. In this
diff --git a/site/docs/skylark/tutorial-sharing-variables.md b/site/docs/skylark/tutorial-sharing-variables.md
index 4cfb364289..2cc7724035 100644
--- a/site/docs/skylark/tutorial-sharing-variables.md
+++ b/site/docs/skylark/tutorial-sharing-variables.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Sharing variables
+title: Sharing Variables
 ---
 
-# Sharing variables
+# Sharing Variables
 
 `BUILD` files are intended to be simple and declarative. They will typically
 consist of a series of a target declarations. As your code base and your `BUILD`