Add test for mdbook sources from different places (bazelbuild#4029)

This adds a test demonstrating how `mdbook` can stitch together sources
from multiple locations in the repository.

We have to mirror the workspace structure in a temporary build
directory, enabling `mdbook` to resolve relative links between files
regardless of their package or generation method.

Author: mgeisler

extensions/mdbook/test/stitched/BUILD.bazel

@@ -0,0 +1,30 @@
+load("@bazel_skylib//rules:build_test.bzl", "build_test")
+load("//:defs.bzl", "mdbook")
+
+# This shows how mdBook can include sources from anywhere in the
+# repository. However, because mdBook only processes files located
+# under the 'src' directory (as configured in book.toml), any files
+# from outside the book's package must be rebased into the 'src'
+# directory using genrules or other means. The rule's process_wrapper
+# ensures that the relative directory structure of these "stitched"
+# files is preserved in the temporary build directory.
+
+mdbook(
+    name = "stitched",
+    srcs = [
+        # The main navigation file for the book.
+        "//test/stitched/src:SUMMARY.md",
+        # A file rebased from a sibling directory into the book's src/
+        # directory.
+        "//test/stitched/src:rebased",
+        # A file generated within a subpackage and placed in the
+        # book's src/ directory.
+        "//test/stitched/src:generated",
+    ],
+    book = "book.toml",
+)
+
+build_test(
+    name = "stitched_test",
+    targets = [":stitched"],
+)

extensions/mdbook/test/stitched/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["Stitched Test"]
+language = "en"
+src = "src"
+title = "Stitched Test Book"

extensions/mdbook/test/stitched/other_srcs/BUILD.bazel

@@ -0,0 +1 @@
+exports_files(["chapter_2.md"])

extensions/mdbook/test/stitched/other_srcs/chapter_2.md

@@ -0,0 +1,2 @@
+# Chapter 2
+Other source.

extensions/mdbook/test/stitched/src/BUILD.bazel

@@ -0,0 +1,19 @@
+exports_files(["SUMMARY.md"])
+
+# Rebase a file from a different directory into the book's source
+# directory. This is necessary because mdBook only processes files
+# located under the 'src' directory (as configured in book.toml).
+genrule(
+    name = "rebased",
+    srcs = ["//test/stitched/other_srcs:chapter_2.md"],
+    outs = ["chapter_2.md"],
+    cmd = "cp $< $@",
+    visibility = ["//test/stitched:__pkg__"],
+)
+
+genrule(
+    name = "generated",
+    outs = ["chapter_3.md"],
+    cmd = "echo '# Chapter 3\nGenerated source.' > $@",
+    visibility = ["//test/stitched:__pkg__"],
+)

extensions/mdbook/test/stitched/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Chapter 1 (Local source)](chapter_1.md)
+- [Chapter 2 (Rebased from sibling directory)](chapter_2.md)
+- [Chapter 3 (Generated in subpackage)](chapter_3.md)

extensions/mdbook/test/stitched/src/chapter_1.md

@@ -0,0 +1,2 @@
+# Chapter 1
+Local source.