Generate all rules per page

Summary:
# This diff stack
Separate the rules at https://buck2.build/docs/prelude/globals/ into separate pages. Each page will have it's own page. With such change it will be more clean and it will be faster  to open the page.

# This diff

This diff generate each page for each rule in prelude and change the side bar config.

Update the broken link in the next diff

Reviewed By: scottcao

Differential Revision: D73704334

fbshipit-source-id: 3004207f6aa0a0edde8de7f286a5465172d525e7

Author: Nero5023

docs/api.md

@@ -6,7 +6,7 @@ for most purposes it can be considered a subset of Python. There are three main
 places you can write Starlark in Buck2:
 
 - In `BUCK` files, where you can define the rules. The most interesting
-  functions are [the rules themselves](../prelude/globals), but you will often
+  functions are [the rules themselves](../prelude/rules/), but you will often
   use the [builtin Starlark functions](starlark) (most of which are the same as
   in Python), and a few of the [build functions](build) (e.g. `glob`).
 - In rule definitions, where you can use the same Starlark standard functions,

docs/concepts/build_rule.md

@@ -19,17 +19,17 @@ Buck2 comes with a collection of built-in build rules for many common build
 procedures. For example:
 
 - Compiling Java code against the Android SDK is a common procedure, so Buck2
-  provides the [`android_library`](../../prelude/globals#android_library) build
+  provides the [`android_library`](../../prelude/rules/android_library) build
   rule
 - The final product of most Android development is an APK, so you can use the
-  [`android_binary`](../../prelude/globals#android_binary) build rule to create
-  an APK
+  [`android_binary`](../../prelude/rules/android_binary) build rule to create an
+  APK
 
 ## Source files as inputs to build rules
 
 Most build rules specify source files as inputs. For example, a
-[`cxx_library`](../../prelude/globals#cxx_library) rule would specify `.cpp`
-files as inputs.
+[`cxx_library`](../../prelude/rules/cxx_library) rule would specify `.cpp` files
+as inputs.
 
 To support specifying these files:
 
@@ -61,13 +61,13 @@ Buck2 enforces these rules regarding source file access:
 
    - The other package explicitly _exports_ those header files
    - This is done using the `exported_headers` argument
-   - See the [`cxx_library`](../../prelude/globals#cxx_library) documentation
-     for details
+   - See the [`cxx_library`](../../prelude/rules/cxx_library) documentation for
+     details
 
 3. **Accessing Functionality**: To use code from other packages:
    - Use the artifacts produced by build rules in those packages
    - Specify those build rules as _dependencies_
-   - Example: A [`cxx_binary`](../../prelude/globals/#cxx_binary) can use a
+   - Example: A [`cxx_binary`](../../prelude/rules/cxx_binary) can use a
      `cxx_library` from another package by taking it as a dependency
 
 #### Using Symlinks (Not Recommended)
@@ -99,12 +99,12 @@ Dependencies are specified in several ways:
 
 ### Examples:
 
-The output of a [`java_library`](../../prelude/globals/#java_library) rule is a
-JAR file. If a `java_library` rule specifies another `java_library` rule as a
+The output of a [`java_library`](../../prelude/rules/java_library) rule is a JAR
+file. If a `java_library` rule specifies another `java_library` rule as a
 dependency, the JAR file produced by the specified rule is added to the
 classpath for the `java_library` that depends on it.
 
-If a [`java_binary`](../../prelude/globals/#java_binary) rule specifies a
+If a [`java_binary`](../../prelude/rules/java_binary) rule specifies a
 `java_library` rule as a dependency, the JAR file for the specified
 `java_library` is available on the classpath for the `java_binary`.
 
@@ -121,7 +121,7 @@ Buck2 guarantees that any dependencies that a rule lists that are required to
 build that rule are built successfully _before_ Buck2 builds the rule itself.
 
 Note that there can be special cases—such as
-[`apple_bundle`](../../prelude/globals/#apple_bundle)—where a rule's listed
+[`apple_bundle`](../../prelude/rules/apple_bundle)—where a rule's listed
 dependencies do not actually need to be built before the rule.
 
 ### Visibility
@@ -150,11 +150,11 @@ category of generic build rules called _genrules_.
 With genrules, you can perform arbitrary operations using shell scripts. The
 genrules supported by Buck2 are:
 
-- [`genrule`](../../prelude/globals/#genrule)
-- [`apk_genrule`](../../prelude/globals/#apk_genrule)
-- [`cxx_genrule`](../../prelude/globals/#cxx_genrule)
-- [`jar_genrule`](../../prelude/globals/#jar_genrule)
-- [`js_bundle_genrule`](../../prelude/globals/#js_bundle_genrule)
+- [`genrule`](../../prelude/rules/genrule)
+- [`apk_genrule`](../../prelude/rules/apk_genrule)
+- [`cxx_genrule`](../../prelude/rules/cxx_genrule)
+- [`jar_genrule`](../../prelude/rules/jar_genrule)
+- [`js_bundle_genrule`](../../prelude/rules/js_bundle_genrule)
 
 ### Multiple output files with genrules
 

docs/concepts/key_concepts.md

@@ -12,10 +12,9 @@ Buck2 has a number of fundamental concepts:
 - A [**_build rule_**](build_rule.md) describes how to produce an output file
   from a set of input files. Most build rules are specific to a particular
   language or platform. For example, you would use the
-  [`cxx_binary`](../../prelude/globals/#cxx_binary) rule to create a C++ binary,
-  but you would use the
-  [`android_binary`](../../prelude/globals/#android_binary) rule to create an
-  Android APK.
+  [`cxx_binary`](../../prelude/rules/cxx_binary) rule to create a C++ binary,
+  but you would use the [`android_binary`](../../prelude/rules/android_binary)
+  rule to create an Android APK.
 - A [**_build target_**](build_target.md) is a string that uniquely identifies a
   build rule. It can be thought of as a URI for the build rule within the Buck2
   project.

docs/rule_authors/writing_toolchains.md

@@ -134,7 +134,7 @@ instead explicitly downloads and tracks them as part of the build.
 Doing is typically as follows:
 
 - Download the tools, e.g. using the
-  [`http_archive`](../../prelude/globals/#http_archive) rule (see the
+  [`http_archive`](../../prelude/rules/http_archive) rule (see the
   [Zig-based C++ toolchain in the prelude](https://github.com/facebook/buck2/tree/main/prelude/toolchains/cxx/zig)
   as an example).
 - Expose those tools as [`RunInfo`](../../api/build/RunInfo/) providers in rules

docs/users/cheatsheet.md

@@ -91,8 +91,8 @@ $(query_targets_and_outputs [SEPARATOR] "queryfunction(:foo)")
 ```
 
 Note, however, that the query macros are supported only for rule attributes of
-type `attrs.arg`, such as [`genrule`](../../prelude/globals/#genrule) and
-[`apk_genrule`](../../prelude/globals/#apk_genrule).
+type `attrs.arg`, such as [`genrule`](../../prelude/rules/genrule) and
+[`apk_genrule`](../../prelude/rules/apk_genrule).
 
 ### How do I find the dependencies for a target?
 

prelude/docs/rules.bzl

@@ -10,4 +10,4 @@
 
 load("@prelude//:rules.bzl", _rules = "rules")
 
-load_symbols(_rules)
+load_symbols({name: namespace(name = r) for name, r in _rules.items()})

website/config_impl.ts

@@ -60,7 +60,7 @@ const themeConfig: ClassicPresetConfig = ({
         activeBaseRegex: '/docs/api',
       },
       {
-        to: '/docs/prelude/globals',
+        to: '/docs/prelude/rules',
         position: 'left',
         label: 'Rules',
         activeBasePath: '/docs/prelude',

website/gen_docs.py

@@ -64,9 +64,9 @@ def copy_starlark_docs() -> None:
         write_file(base_path / (name + ".generated.md"), prefix + read_file(x))
 
 
-def generate_api_docs(buck: str) -> None:
+def generate_prelude_rules_docs(buck: str) -> None:
     with tempfile.TemporaryDirectory() as tmp:
-        base_dir = Path("docs") / "prelude"
+        base_dir = Path("docs") / "prelude" / "rules"
         setup_gen_dir(base_dir)
         # Actually generate the docs
         print("Running Buck...")
@@ -79,16 +79,23 @@ def generate_api_docs(buck: str) -> None:
             check=True,
         )
 
-        src = read_file(Path(tmp) / "prelude" / "docs" / "rules.bzl.md")
-        dest = base_dir / "globals.generated.md"
+        # Copy the files under Path(tmp) / prelude / docs / rules to base_dir
+        folder = Path(tmp) / "prelude" / "docs" / "rules.bzl"
+        for orig in folder.glob("*.md"):
+            path = orig.relative_to(folder)
+            dest = base_dir.joinpath(path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(orig, dest)
+
+        index_file_content = (
+            "# Rules\n\nThese rules are available as standard in Buck2.\n"
+        )
 
-        prefix = "---\nid: globals\n---\n"
-        prefix += "# Rules\n\nThese rules are available as standard in Buck2.\n"
-        src = "\n".join(src.splitlines()[1:])
+        os.makedirs(base_dir, exist_ok=True)
+        write_file(base_dir / "index.md", index_file_content)
 
-        os.makedirs(dest.parent, exist_ok=True)
-        write_file(dest, prefix + src)
 
+def generate_api_docs(buck: str) -> None:
     with tempfile.TemporaryDirectory() as tmp:
         base_dir = Path("docs") / "api"
         setup_gen_dir(base_dir)
@@ -254,6 +261,7 @@ def main() -> None:
 
     buck = buck_command(args)
     copy_starlark_docs()
+    generate_prelude_rules_docs(buck)
     generate_api_docs(buck)
     generate_bxl_utils_api_docs(buck)
     generate_help_docs(buck)

website/redirects.ts

@@ -27,9 +27,13 @@ const baseRedirects = [
       from: '/docs/bootstrapping',
     },
     {
-      to: '/docs/prelude/globals',
+      to: '/docs/prelude/rules',
       from: '/docs/api/rules',
     },
+    {
+      to: '/docs/prelude/rules',
+      from: '/docs/prelude/globals',
+    }
   ];
 
 // Redirects that need to be introduced following changes to the generated API docs in D61778036

website/sidebars.ts

@@ -243,7 +243,7 @@ export const sidebars: SidebarsConfig = {
     },
     {
       type: 'doc',
-      id: 'prelude/globals',
+      id: 'prelude/rules/index',
       label: 'Rules',
     },
     {
@@ -274,6 +274,14 @@ export const sidebars: SidebarsConfig = {
       ],
     }
   ],
+  'ruleSidebar': [
+    {
+      type: 'category',
+      label: 'Rules',
+      items: [{ type: 'autogenerated', dirName: 'prelude/rules' }],
+      link: { type: 'doc', id: 'prelude/rules/index' },
+    }
+  ],
 };
 
 export function postProcessItems(items) {