build: avoid file collisions in docs-content (#18691)

Currently we always move guides, overviews, example files into
the `docs-content` by their basename. This means that no guides,
overviews, example files with the same name can exist. The last
one being processed by Bazel overwrites the previous ones.

This can be currently observed in the docs where the custom
form-field control example incorrectly displays the MDC-based
form-field custom control example. Ultimately breaking StackBlitz.

For example: https://material.angular.io/guide/creating-a-custom-form-field-control.
Click on the first example, and open it on StackBlitz.

We can fix this by preserving the directories where the guides,
overviews and example files have been copied from. This also allows
us to have multiple overviews in a package without the risk of
collisions.

Note: Needs an corresponding change in the material.angular.io repo.

Author: mmalerba

tools/dgeni/index.bzl

@@ -1,15 +1,13 @@
 """
   Implementation of the "_dgeni_api_docs" rule. The implementation runs Dgeni with the
-  specified entry points and outputs the API docs into a package relative directory.
+  specified entry points and outputs the API docs as `DefaultInfo` declared output files.
 """
 
 def _dgeni_api_docs(ctx):
     input_files = ctx.files.srcs
     args = ctx.actions.args()
     expected_outputs = []
-
-    output_dir_name = ctx.attr.name
-    output_dir_path = "%s/%s/%s" % (ctx.bin_dir.path, ctx.label.package, output_dir_name)
+    output_dir_path = "%s/%s" % (ctx.bin_dir.path, ctx.label.package)
 
     # Do nothing if there are no input files. Bazel will throw if we schedule an action
     # that returns no outputs.
@@ -41,17 +39,15 @@ def _dgeni_api_docs(ctx):
                 # Declare the output for the current entry-point. The output file will always follow the
                 # same format: "{output_folder}/{package_name}-{entry_point_name}.html"
                 # (e.g. "api-docs/material-slider-testing.html")
-                ctx.actions.declare_file("%s/%s-%s.html" %
-                                         (output_dir_name, package_name, entry_point.replace("/", "-"))),
+                ctx.actions.declare_file("%s-%s.html" %
+                                         (package_name, entry_point.replace("/", "-"))),
             ]
 
         # Small workaround that ensures that the "ripple" API doc is properly exposed as an output
         # of the packaging rule. Technically Dgeni should not output the "ripple" directory as
         # its own entry-point. TODO(devversion): Support sub API docs for entry-points
         if package_name == "material":
-            expected_outputs += [
-                ctx.actions.declare_file("%s/%s-%s.html" % (output_dir_name, package_name, "ripple")),
-            ]
+            expected_outputs += [ctx.actions.declare_file("%s-%s.html" % (package_name, "ripple"))]
 
     # Run the Dgeni bazel executable which builds the documentation output based on the
     # configured rule attributes.

tools/package-docs-content/index.bzl

@@ -25,12 +25,18 @@ def _package_docs_content(ctx):
     # output file which will be added to the executable arguments.
     for input_target, section_name in ctx.attr.srcs.items():
         section_files = input_target.files.to_list()
+        base_dir = "%s" % (input_target.label.package)
 
         for input_file in section_files:
+            # Creates a relative path from the input file. We don't want to include the full
+            # path in docs content. e.g. `docs-content/overviews/cdk/src/cdk/a11y/a11y.html`.
+            # Instead, we want the path to be: `docs-content/overviews/cdk/a11y/a11y.html`.
+            section_relative_file_name = input_file.short_path[len(base_dir):]
+
             # For each input file, we want to create a copy that is stored in the output directory
             # within its specified section. e.g. "pkg_bin/docs-content/guides/getting-started.html"
             output_file = ctx.actions.declare_file(
-                "%s/%s/%s" % (output_dir, section_name, input_file.basename),
+                "%s/%s/%s" % (output_dir, section_name, section_relative_file_name),
             )
 
             # Add the output file to the expected outputs so that Bazel throws an error if the file