Create the "C++ and Bazel" and "Java and Bazel" pages.

PiperOrigin-RevId: 168687598

4 files changed, 194 insertions, 71 deletions

diff --git a/site/docs/bazel-and-cpp.md b/site/docs/bazel-and-cpp.md
new file mode 100644
index 0000000000..84e9ed7549
--- /dev/null
+++ b/site/docs/bazel-and-cpp.md
@@ -0,0 +1,84 @@
+---
+layout: documentation
+title: C++ and Bazel
+---
+
+# C++ and Bazel
+
+This page contains resources that help you use Bazel with C++ projects. It links
+to a tutorial, build rules, and other information specific to building C++
+projects with Bazel.
+
+## Contents
+
+- [Working with Bazel](#working-with-bazel)
+- [Best practices](#best-practices)
+   - [BUILD files](#build-files)
+   - [Include paths](#include-paths)
+
+## Working with Bazel
+
+The following resources will help you work with Bazel on C++ projects:
+
+*  [Tutorial: Building a C++ project](tutorial/cpp.html)
+*  [C++ common use cases](tutorial/cpp-use-cases.html)
+*  [C/C++ rules](https://docs.bazel.build/versions/master/be/c-cpp.html)
+
+## Best practices
+
+In addition to [general Bazel best practices](best-practices.html), below are
+best practices specific to C++ projects.
+
+### BUILD files
+
+Follow the guidelines below when creating your BUILD files:
+
+*  Each BUILD file should contain one [`cc_library`](https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library)
+   rule target per compilation unit in the directory.
+
+*  We recommend that you granularize your C++ libraries as much as possible to
+   maximize incrementality and parallelize the build.
+
+*  If there is a single source file in `srcs`, name the library the same as
+   that C++ file's name. This library should contain C++ file(s), any matching
+   header file(s), and the library's direct dependencies. For example:
+
+   ```python
+   cc_library(
+       name = "mylib",
+       srcs = ["mylib.cc"],
+       hdrs = ["mylib.h"],
+       deps = [":lower-level-lib"]
+   )
+   ```
+
+*  Use one `cc_test` rule target per `cc_library` target in the file. Name the
+   target `[library-name]_test` and the source file `[library-name]_test.cc`.
+   For example, a test target for the `mylib` library target shown above would
+   look like this:
+
+   ```python
+   cc_test(
+       name = "mylib_test",
+       srcs = ["mylib_test.cc"],
+       deps = [":mylib"]
+   )
+   ```
+
+### Include paths
+
+Follow these guidelines for include paths:
+
+*  Make all include paths relative to the workspace directory.
+
+*  Use quoted includes (`#include "foo/bar/baz.h"`) for non-system headers, not
+   angle-brackets (`#include <foo/bar/baz.h>`).
+
+*  Avoid using UNIX directory shortcuts, such as `.` (current directory) or `..`
+   (parent directory).
+
+*  For legacy or `third_party` code that requires includes pointing outside the
+   project repository, such as external repository includes requiring a prefix,
+   use the [`include_prefix`](https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.include_prefix)
+   and [`strip_include_prefix`](https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.strip_include_prefix)
+   arguments on the `cc_library` rule target.
diff --git a/site/docs/bazel-and-java.md b/site/docs/bazel-and-java.md
new file mode 100644
index 0000000000..10a6dd073e
--- /dev/null
+++ b/site/docs/bazel-and-java.md
@@ -0,0 +1,97 @@
+---
+layout: documentation
+title: Java and Bazel
+---
+
+# Java and Bazel
+
+This page contains resources that help you use Bazel with Java projects. It
+links to a tutorial, build rules, and other information specific to building
+Java projects with Bazel.
+
+## Contents
+
+- [Working with Bazel](#working-with-bazel)
+- [Migrating to Bazel](#migrating-to-bazel)
+- [Best practices](#best-practices)
+   - [Directory structure](#directory-structure)
+   - [BUILD files](#build-files)
+- [Java and Skylark](#java-and-skylark)
+
+## Working with Bazel
+
+The following resources will help you work with Bazel on Java projects:
+
+*  [Tutorial: Building a Java Project](tutorial/java.html)
+*  [Java rules](https://docs.bazel.build/versions/master/be/java.html)
+
+## Migrating to Bazel
+
+If you currently build your Java projects with Maven, follow the steps in the
+migration guide to start building your Maven projects with Bazel:
+
+*  [Migrating from Maven to Bazel](migrate-maven.html)
+
+## Best practices
+
+In addition to [general Bazel best practices](best-practices.html), below are
+best practices specific to Java projects.
+
+### Directory structure
+
+Prefer Maven's standard directory layout (sources under `src/main/java`, tests
+under `src/test/java`).
+
+### BUILD files
+
+Follow these guidelines when creating your BUILD files:
+
+*  Use one BUILD file per package containing Java sources.
+
+*  Every BUILD file should contain one `java_library` rule that looks like this:
+
+   ```python
+   java_library(
+       name = "directory-name",
+       srcs = glob(["*.java"]),
+      deps = [...],
+   )
+   ```
+*  The name of the library should be the name of the directory containing the
+   BUILD file.
+
+*  The sources should be a non-recursive [`glob`](https://docs.bazel.build/versions/master/be/functions.html#glob)
+   of all Java files in the directory.
+
+*  Tests should be in a matching directory under `src/test` and depend on this
+   library.
+
+## Java and Skylark
+
+**Note**: Extending Bazel with Skylark is for advanced build and test scenarios.
+You do not need to use Skylark when getting started with Bazel.
+
+The following [Skylark](https://docs.bazel.build/versions/master/skylark/concepts.html)
+modules, configuration fragments, and providers will help you extend Bazel's
+capabilities when building your Java projects:
+
+*  Modules:
+
+   *  [`java_annotation_processing`](skylark/lib/java_annotation_processing.html)
+   *  [`java_common`](skylark/lib/java_common.html)
+   *  [`java_compilation_info`](skylark/lib/java_compilation_info.html)
+   *  [`java_output`](skylark/lib/java_output.html)
+   *  [`java_output_jars`](skylark/lib/java_output_jars.html)
+   *  [`java_proto_common`](skylark/lib/java_proto_common.html)
+   *  [`JavaRuntimeClasspathProvider`](skylark/lib/JavaRuntimeClasspathProvider.html)
+   *  [`JavaRuntimeInfo`](skylark/lib/JavaRuntimeInfo.html)
+   *  [`JavaToolchainSkylarkApiProvider`](skylark/lib/JavaToolchainSkylarkApiProvider.html)
+
+*  Configuration fragments:
+
+   *  [`java`](skylark/lib/java.html)
+
+*  Providers:
+
+   *  [`java`](skylark/lib/JavaSkylarkApiProvider.html)
+   *  [`JavaInfo`](skylark/lib/JavaInfo.html)
diff --git a/site/docs/best-practices.md b/site/docs/best-practices.md
index b69e665728..5ec3be1735 100644
--- a/site/docs/best-practices.md
+++ b/site/docs/best-practices.md
@@ -41,14 +41,10 @@ This document uses the requirement levels described in
    - [Repository rules](#repository-rules)
    - [Custom BUILD files](#custom-build-files)
    - [Skylark repository rules](#skylark-repository-rules)
-- [Java](#java)
-   - [Directory structure](#directory-structure)
-   - [BUILD files](#build-files)
-- [C++](#c)
-   - [BUILD files](#build-files)
-   - [Include paths](#include-paths)
-- [Protos](#protos)
-   - [Recommended Code Organization](#recommended-code-organization)
+- [Programming languages](#programming-languages)
+   - [C++ and Bazel](#c-and-bazel)
+   - [Java and Bazel](#java-and-bazel)
+   - [Protos and Bazel](#protos-and-bazel)
 
 # General structure
 
@@ -163,76 +159,22 @@ Avoid using `repository_ctx.execute` when possible.  For example, when using a n
 library that has a build using Make, it is preferable to use `respository_ctx.download()` and then
 write a BUILD file that builds it, instead of running `ctx.execute(["make"])`.
 
-# Java
 
-## Directory structure
+# Programming languages
 
-Prefer Maven's standard directory layout (sources under `src/main/java`, tests under
-`src/test/java`).
+This section describes best practices for specific programming languages.
 
-## BUILD files
+## C++ and Bazel
 
-Use one BUILD file per package containing Java sources. Every BUILD file should contain one
-`java_library` rule that looks like this:
+For best practices for C++ projects, see [C++ and Bazel](bazel-and-cpp.md).
 
-```python
-java_library(
-    name = "directory-name",
-    srcs = glob(["*.java"]),
-    deps = [...],
-)
-```
+## Java and Bazel
 
-The name of the library should be the name of the directory containing the BUILD file.  The sources
-should be a non-recursive glob of all Java files in the directory.
+For best practices for Java projects, see [Java and Bazel](bazel-and-java.md).
 
-Tests should be in a matching directory under `src/test` and depend on this library.
+## Protos and Bazel
 
-# C++
-
-## BUILD files
-
-Each BUILD file should contain one `cc_library` rule target per compilation unit in the directory.
-C++ libraries should be as fine-grained as possible to provide as much incrementality as possible.
-
-If there is a single source file in `srcs`, the library should be named based on that C++ file's
-name. This library should contain a C++ file(s), any matching header file(s), and the library's
-direct dependencies.  For example,
-
-```python
-cc_library(
-    name = "mylib",
-    srcs = ["mylib.cc"],
-    hdrs = ["mylib.h"],
-    deps = [":lower-level-lib"]
-)
-```
-
-There should be one `cc_test` rule target per `cc_library` target in the file. The `cc_test`'s
-source should be a file named `[libname]_test.cc`.  For example, a test for the target above might
-look like:
-
-```
-cc_test(
-    name = "mylib_test",
-    srcs = ["mylib_test.cc"],
-    deps = [":mylib"]
-)
-```
-
-## Include paths
-
-All include paths should be relative to the workspace directory. Use `includes` only if a public
-header needs to be widely used at a non-workspace-relative path (for legacy or `third_party` code).
-Otherwise, prefer to use the `copts` attribute, not the `includes` attribute.
-
-Using `cc_inc_library` is discouraged, prefer `copts` or `includes`.
-See [the design document](https://docs.google.com/document/d/18qUWh0uUiJBv6ZOySvp6DEV0NjVnBoEy-r-ZHa9cmhU/edit#heading=h.kmep1cl5ym9k)
-on C++ include directories for reasoning.
-
-# Protos
-
-## Recommended Code Organization
+Recommended code organization:
 
 -  One `proto_library` rule per `.proto` file.
 -  A file named `foo.proto` will be in a rule named `foo_proto`, which is located in the same
diff --git a/site/docs/tutorial/cpp-use-cases.md b/site/docs/cpp-use-cases.md
index 2b39bc56c9..07f42f458f 100644
--- a/site/docs/tutorial/cpp-use-cases.md
+++ b/site/docs/cpp-use-cases.md
@@ -9,7 +9,7 @@ Introduction to Bazel: Common C++ Build Use Cases
 Here you will find some of the most common use cases for building C++ projects
 with Bazel. If you have not done so already, get started with building C++
 projects with Bazel by completing the tutorial
-[Introduction to Bazel: Build a C++ Project](cpp.md).
+[Introduction to Bazel: Build a C++ Project](tutorial/cpp.html).
 
 ## Contents