docs: restore docs for Bash/Zsh completion
The docs were removed seemingly by accident.
Also change Markdown headers with <a> tags to HTML
<hN> tags with IDs, because the Jekyll version we
use to render .md to .html ignores the <a> tags
and respects only the <hN> tags when creating
links to headings.
See https://github.com/bazelbuild/bazel/issues/4255#issuecomment-432120127
Fixes https://github.com/bazelbuild/bazel/issues/4255
Closes #6472.
Change-Id: I024e1d5025849db3a1484a41d58287b59973a33f
PiperOrigin-RevId: 218679796
diff --git a/site/docs/completion.md b/site/docs/completion.md
new file mode 100644
index 0000000..1f6566d
--- /dev/null
+++ b/site/docs/completion.md
@@ -0,0 +1,90 @@
+---
+layout: documentation
+title: "Command-Line Completion"
+---
+
+# Command-Line Completion
+
+You can enable command-line completion (also known as tab-completion) in Bash
+and Zsh. This lets you tab-complete command names, flags names and flag values,
+and target names.
+
+<h2 id="bash">Bash completion</h2>
+
+Bazel comes with a Bash completion script.
+
+If you installed Bazel:
+
+* From the APT repository, then you're done -- the Bash completion script is
+ already installed in `/etc/bash_completion.d`.
+
+* From the installer downloaded from GitHub, then:
+ 1. Locate the absolute path of the completion file. The installer copied it
+ to the `bin` directory.
+
+ Example: if you ran the installer with `--user`, this will be
+ `$HOME/.bazel/bin`. If you ran the installer as root, this will be
+ `/usr/local/bazel/bin`.
+ 2. Do one of the following:
+ * Either copy this file to your completion directory (if you have
+ one).
+
+ Example: on Ubuntu this is the `/etc/bash_completion.d` directory.
+ * Or source the completion file from Bash's RC file.
+
+ Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+ or `~/.bash_profile` (on macOS), using the path to your completion
+ file's absolute path:
+
+ ```
+ source /path/to/bazel-complete.bash
+ ```
+
+* Via [bootstrapping](install-compile-source.html), then:
+ 1. Build the completion script:
+
+ ```
+ bazel build //scripts:bazel-complete.bash
+ ```
+ 2. The completion file is built under
+ `bazel-bin/scripts/bazel-complete.bash`.
+
+ Do one of the following:
+ * Either copy this file to your completion directory (if you have
+ one).
+
+ Example: on Ubuntu this is the `/etc/bash_completion.d` directory
+ * Or copy it somewhere on your local disk, e.g. to `$HOME`, and
+ source the completion file from Bash's RC file.
+
+ Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+ or `~/.bash_profile` (on macOS), using the path to your completion
+ file's absolute path:
+
+ ```
+ source /path/to/bazel-complete.bash
+ ```
+
+<h2 name="zsh">Zsh completion</h2>
+
+Bazel also comes with a Zsh completion script. To install it:
+
+1. Add this script to a directory on your `$fpath`:
+
+ ```
+ fpath[1,0]=~/.zsh/completion/
+ mkdir -p ~/.zsh/completion/
+ cp scripts/zsh_completion/_bazel ~/.zsh/completion
+ ```
+
+ You may have to call `rm -f ~/.zcompdump; compinit`
+ the first time to make it work.
+
+2. Optionally, add the following to your .zshrc.
+
+ ```
+ # This way the completion script does not have to parse Bazel's options
+ # repeatedly. The directory in cache-path must be created manually.
+ zstyle ':completion:*' use-cache on
+ zstyle ':completion:*' cache-path ~/.zsh/cache
+ ```
diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index eb8a5ac..ded9f2b 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -3,7 +3,7 @@
title: Installing Bazel on macOS
---
-# <a name="mac-os-x"></a>Installing Bazel on macOS
+<h1 id="mac-os-x">Installing Bazel on macOS</h1>
Install Bazel on macOS using one of the following methods:
@@ -13,10 +13,10 @@
Bazel comes with two completion scripts. After installing Bazel, you can:
-* Access the [bash completion script](install.md)
-* Install the [zsh completion script](install.md)
+* Access the [bash completion script](completion.md#bash)
+* Install the [zsh completion script](completion.md#zsh)
-## <a name="install-with-installer-mac-os-x"></a>Installing using binary installer
+<h2 id="install-with-installer-mac-os-x">Installing using binary installer</h2>
The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
@@ -74,7 +74,7 @@
```
To update to a newer release of Bazel, download and install the desired version.
-## <a name="install-on-mac-os-x-homebrew"></a>Installing using Homebrew
+<h2 id="install-on-mac-os-x-homebrew">Installing using Homebrew</h2>
### Step 1: Install Homebrew on macOS
diff --git a/site/docs/install-ubuntu.md b/site/docs/install-ubuntu.md
index ba36e6d..214246f 100644
--- a/site/docs/install-ubuntu.md
+++ b/site/docs/install-ubuntu.md
@@ -3,7 +3,7 @@
title: Installing Bazel on Ubuntu
---
-# <a name="ubuntu"></a>Installing Bazel on Ubuntu
+<h1 id="ubuntu">Installing Bazel on Ubuntu</h1>
Supported Ubuntu Linux platforms:
@@ -18,10 +18,10 @@
Bazel comes with two completion scripts. After installing Bazel, you can:
-* Access the [bash completion script](install.md)
-* Install the [zsh completion script](install.md)
+* Access the [bash completion script](completion.md#bash)
+* Install the [zsh completion script](completion.md#zsh)
-## <a name="install-with-installer-ubuntu"></a>Installing using binary installer
+<h2 id="install-with-installer-ubuntu">Installing using binary installer</h2>
The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
@@ -66,7 +66,7 @@
You can also add this command to your `~/.bashrc` file.
-## <a name="install-on-ubuntu"></a> Using Bazel custom APT repository
+<h2 id="install-on-ubuntu"> Using Bazel custom APT repository</h2>
### Step 1: Install the JDK
