Split API docs reference for #[builder] into multiple pages (#164)

website/.vitepress/config.mts

@@ -12,7 +12,43 @@ export default defineConfig({
     cleanUrls: true,
     lastUpdated: true,
 
+    vite: {
+        plugins: [
+            {
+                name: "inject-abbreviations",
+                transform: {
+                    order: "pre",
+                    handler(src, id) {
+                        if (!id.endsWith(".md")) {
+                            return;
+                        }
+
+                        const abbrs = {
+                            Member: "Struct field or function argument",
+                            member: "Struct field or function argument",
+                            members: "Struct fields or function arguments",
+                            ["starting function"]:
+                                "Function that creates the builder (e.g. `builder()`)",
+                            ["finishing function"]:
+                                "Method on the builder struct that finishes building (e.g. `build()` or `call()`)",
+                        };
+
+                        const abbrsStr = Object.entries(abbrs)
+                            .map(([key, value]) => `*[${key}]: ${value}`)
+                            .join("\n");
+
+                        return `${src}\n\n${abbrsStr}`;
+                    },
+                },
+            },
+        ],
+    },
+
     markdown: {
+        languageAlias: {
+            'attr': 'js',
+        },
+
         theme: {
             dark: "dark-plus",
             light: "light-plus",
@@ -155,84 +191,75 @@ export default defineConfig({
             ],
             "/reference": [
                 {
-                    text: "Reference",
+                    text: "#[derive(Builder)] / #[builder]",
+                    link: "/reference/builder",
                     items: [
                         {
-                            text: "#[derive(Builder)] / #[builder]",
-                            link: "/reference/builder",
+                            text: "Top-level",
+                            link: "/reference/builder#top-level-attributes",
                             items: [
                                 {
-                                    text: "Top-level attributes",
-                                    link: "/reference/builder#top-level-attributes",
-                                    items: [
-                                        {
-                                            text: "builder_type",
-                                            link: "/reference/builder#builder-type",
-                                        },
-                                        {
-                                            text: "derive",
-                                            link: "/reference/builder#derive",
-                                        },
-                                        {
-                                            text: "expose_positional_fn",
-                                            link: "/reference/builder#expose-positional-fn",
-                                        },
-                                        {
-                                            text: "finish_fn",
-                                            link: "/reference/builder#finish-fn",
-                                        },
-                                        {
-                                            text: "on",
-                                            link: "/reference/builder#on",
-                                        },
-                                        {
-                                            text: "start_fn",
-                                            link: "/reference/builder#start-fn",
-                                        },
-                                    ],
+                                    text: "builder_type",
+                                    link: "/reference/builder/top-level/builder-type",
+                                },
+                                {
+                                    text: "derive",
+                                    link: "/reference/builder/top-level/derive",
+                                },
+                                {
+                                    text: "finish_fn",
+                                    link: "/reference/builder/top-level/finish-fn",
                                 },
                                 {
-                                    text: "Member attributes",
-                                    link: "/reference/builder#member-attributes",
-                                    items: [
-                                        {
-                                            text: "default",
-                                            link: "/reference/builder#default",
-                                        },
-                                        {
-                                            text: "finish_fn",
-                                            link: "/reference/builder#finish-fn-1",
-                                        },
-                                        {
-                                            text: "into",
-                                            link: "/reference/builder#into",
-                                        },
-                                        {
-                                            text: "name",
-                                            link: "/reference/builder#name",
-                                        },
-                                        {
-                                            text: "skip",
-                                            link: "/reference/builder#skip",
-                                        },
-                                        {
-                                            text: "start_fn",
-                                            link: "/reference/builder#start-fn-1",
-                                        },
-                                    ],
+                                    text: "on",
+                                    link: "/reference/builder/top-level/on",
+                                },
+                                {
+                                    text: "start_fn",
+                                    link: "/reference/builder/top-level/start-fn",
                                 },
                             ],
                         },
                         {
-                            text: "#[bon]",
-                            link: "/reference/bon",
-                        },
-                        {
-                            text: "Other items on docs.rs",
-                            link: "https://docs.rs/bon/latest/bon/",
+                            text: "Member",
+                            link: "/reference/builder#member-attributes",
+                            items: [
+                                {
+                                    text: "default",
+                                    link: "/reference/builder/member/default",
+                                },
+                                {
+                                    text: "finish_fn",
+                                    link: "/reference/builder/member/finish-fn",
+                                },
+                                {
+                                    text: "into",
+                                    link: "/reference/builder/member/into",
+                                },
+                                {
+                                    text: "name",
+                                    link: "/reference/builder/member/name",
+                                },
+                                {
+                                    text: "skip",
+                                    link: "/reference/builder/member/skip",
+                                },
+                                {
+                                    text: "start_fn",
+                                    link: "/reference/builder/member/start-fn",
+                                },
+                            ],
                         },
                     ],
                 },
+                {
+                    text: "#[bon]",
+                    link: "/reference/bon",
+                },
+                {
+                    text: "Other items on docs.rs",
+                    link: "https://docs.rs/bon/latest/bon/",
+                },
             ],
         },
     },

website/.vitepress/theme/style.css

@@ -1,5 +1,5 @@
-/* Prevent wrapping of inline code snippets */
-code, .nobr {
+/* Opt-in nowrap via a class */
+.nobr {
     white-space: nowrap;
 }
 

website/blog/bon-builder-generator-v2-release.md

@@ -74,7 +74,7 @@ This has been a topic of [controversy](https://github.com/elastio/bon/issues/15)
 
 The main reason for removing this is to make `bon` more obvious and intuitive. Rust's core pillar is "being explicit". By having automatic `Into` conversions `bon` v1 introduced magical implicit behaviour, that also could lead to some footguns. For a detailed explanation of the potential footguns, see the ["Into Conversions In-Depth"](../guide/patterns/into-conversions-in-depth) page.
 
-Now, if you want to enable `Into` conversions for a set of members, you can use the new [`#[builder(on(type_pattern, into))]`](../reference/builder#on) attribute. It allows you to specify the type that you want to enable `Into` conversions for explicitly.
+Now, if you want to enable `Into` conversions for a set of members, you can use the new [`#[builder(on(type_pattern, into))]`](../reference/builder/top-level/on) attribute. It allows you to specify the type that you want to enable `Into` conversions for explicitly.
 
 Let's review an example of a migration that you need to do when upgrading to `bon` v2.
 

website/blog/bon-builder-v2-1-release.md

@@ -261,7 +261,3 @@ You can leave comments for this post on the platform of your choice:
 
 [`bon`]: https://github.com/elastio/bon
 [`typed-builder`]: https://docs.rs/typed-builder/latest/typed_builder/
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments

website/blog/bon-builder-v2-2-release.md

@@ -59,7 +59,7 @@ cargo fmt
 
 ### Derive `Clone` and `Debug` for the builder
 
-A new attribute is now supported at the top level. You can add [`#[builder(derive(...))]`](../reference/builder#derive) to ask `bon` to generate implementations of `Clone` or `Debug` for the builder.
+A new attribute is now supported at the top level. You can add [`#[builder(derive(...))]`](../reference/builder/top-level/derive) to ask `bon` to generate implementations of `Clone` or `Debug` for the builder.
 
 This helps with reusing [partial builders](../guide/patterns/conditional-building#shared-partial-builder), because now you can clone the builder where only part of the fields are set.
 
@@ -236,8 +236,3 @@ You can leave comments for this post on the platform of your choice:
 
 [`bon`]: https://github.com/elastio/bon
 [@recatek]: https://github.com/recatek
-
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments

website/blog/bon-builder-v2-3-release.md

@@ -32,8 +32,8 @@ As an example, suppose we have a `Treasure` struct with `x` and `y` coordinates
 
 To do that we can use the `#[builder(start_fn)]` attribute. There are two contexts where we can place it, and they both have a different meaning:
 
-- [Top-level `#[builder(start_fn = ...)]`](../reference/builder#start-fn) - configures the name of the starting function and optionally its visibility
-- [Member-level `#[builder(start_fn)]`](../reference/builder#start-fn-1) - configures the member to be a positional parameter on the starting function
+- [Top-level `#[builder(start_fn = ...)]`](../reference/builder/top-level/start-fn) - configures the name of the starting function and optionally its visibility
+- [Member-level `#[builder(start_fn)]`](../reference/builder/member/start-fn) - configures the member to be a positional parameter on the starting function
 
 We'll want to use both of these attributes in our example to give a better name for the starting function that describes its inputs and configure `x` and `y` as positional parameters on the starting function as well.
 
@@ -78,7 +78,7 @@ impl Treasure {
 
 Now let's say we need to know the person who claimed the `Treasure`. While describing the treasure using the current builder syntax we'd like the person who claimed it to specify their first name and last name at the end of the building process.
 
-We can use a similar combination of the [top-level `#[builder(finish_fn = ...)]`](../reference/builder#finish-fn) and the [member-level `#[builder(finish_fn)]`](../reference/builder#finish-fn-1) attributes to do that.
+We can use a similar combination of the [top-level `#[builder(finish_fn = ...)]`](../reference/builder/top-level/finish-fn) and the [member-level `#[builder(finish_fn)]`](../reference/builder/member/finish-fn) attributes to do that.
 
 **Example:**
 
@@ -115,7 +115,7 @@ assert_eq!(treasure.claimed_by_first_name, "Lyra");        // [!code highlight]
 assert_eq!(treasure.claimed_by_last_name, "Heartstrings"); // [!code highlight]
 ```
 
-You may also combine these attributes with [`#[builder(into)]`](../reference/builder#into) or [`#[builder(on(..., into))]`](../reference/builder#into) to reduce the number of `to_owned()` calls a bit. See this described in detail on the new ["Positional members"](../guide/positional-members#into-conversions) page in the guide.
+You may also combine these attributes with [`#[builder(into)]`](../reference/builder/member/into) or [`#[builder(on(..., into))]`](../reference/builder/top-level/on) to reduce the number of `to_owned()` calls a bit. See this described in detail on the new ["Positional members"](../guide/positional-members#into-conversions) page in the guide.
 
 ### Guaranteed MSRV is 1.59.0 now
 
@@ -154,7 +154,3 @@ You can leave comments for this post on the platform of your choice:
 :::
 
 [`bon`]: https://github.com/elastio/bon
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments

website/guide/alternatives.md

@@ -98,8 +98,8 @@ Another difference is that fields of collection types are considered required by
 [map]: https://docs.rs/bon/latest/bon/macro.map.html
 [set]: https://docs.rs/bon/latest/bon/macro.set.html
 [mutators]: https://docs.rs/typed-builder/latest/typed_builder/derive.TypedBuilder.html#mutators
-[bon-on]: ../reference/builder#on
-[bon-into]: ../reference/builder#into
+[bon-on]: ../reference/builder/top-level/on
+[bon-into]: ../reference/builder/member/into
 [bs-into]: https://docs.rs/buildstructor/latest/buildstructor/#into-field
 [db-into]: https://docs.rs/derive_builder/latest/derive_builder/#generic-setters
 [r1]: #special-setter-methods-for-collections

website/guide/compatibility.md

@@ -2,7 +2,7 @@
 
 ## Making a required member optional
 
-It's totally backwards compatible to make a required member optional by changing the type from `T` to `Option<T>` or by adding [`#[builder(default)]`](../reference/builder.md#default) to it.
+It's totally backwards compatible to make a required member optional by changing the type from `T` to `Option<T>` or by adding [`#[builder(default)]`](../reference/builder/member/default) to it.
 
 This is because both required and optional members have a setter that accepts `T` (not wrapped in an `Option`). The only change to the public API when making the required member optional is that a `maybe_`-prefixed setter is added to the builder. That new method accepts an `Option<T>`.
 
@@ -175,33 +175,8 @@ let user = User::builder()
     .build();
 ```
 
-## Adding `#[builder]` to existing code
+## Adding `#[builder]` to existing functions
 
-If your existing code defines functions with positional parameters in its public API that you'd like to change to use builder syntax, but you want to keep the old code compatible with the positional functions API, then you may use `#[builder(expose_positional_fn)]` attribute to keep both syntaxes available.
+Let's suppose you have existing code that defines functions with positional parameters in the public API. You'd like to change it to expose builder syntax instead, but you want to keep the old code compatible with the positional functions API.
 
-See [this attribute's docs](../reference/builder#expose-positional-fn) for details.
-
-**Example:**
-
-```rust ignore
-use bon::builder;
-
-// The previous name of the positional function needs to be specified
-// as the value for `expose_positional_fn`.
-#[builder(expose_positional_fn = example)] // [!code ++]
-fn example(x: u32, y: u32) {}              // [!code --]
-fn example_builder(x: u32, y: u32) {}      // [!code ++]
-
-// The positional function is now available under the specified (old) name
-example(1, 2);
-
-// The builder syntax is also available under the new function name
-example_builder()
-    .x(1)
-    .y(2)
-    .call();
-```
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments
+In this case, you may use the top-level attribute `#[builder(start_fn)]` to keep both syntaxes available. See examples in the [docs for this attribute](../reference/builder/top-level/start-fn#exposing-original-function).

website/guide/inspecting.md

@@ -1,6 +1,6 @@
 # Inspecting
 
-If you want to inspect the values set in the builder for debugging purposes you can leverage the [`#[builder(derive(...))]`](../reference/builder#derive) attribute to derive the [`Debug`](https://doc.rust-lang.org/stable/std/fmt/trait.Debug.html) trait for your builder.
+If you want to inspect the values set in the builder for debugging purposes you can leverage the [`#[builder(derive(...))]`](../reference/builder/top-level/derive) attribute to derive the [`Debug`](https://doc.rust-lang.org/stable/std/fmt/trait.Debug.html) trait for your builder.
 
 **Example:**
 
@@ -30,4 +30,4 @@ assert_eq!(
 builder.is_admin(true).call();
 ```
 
-You can also derive the [`Clone`](https://doc.rust-lang.org/stable/std/clone/trait.Clone.html) trait for your builder using this same attribute. See more details in the [reference for the `#[builder(derive(...))]` attribute](../reference/builder#derive).
+You can also derive the [`Clone`](https://doc.rust-lang.org/stable/std/clone/trait.Clone.html) trait for your builder using this same attribute. See more details in the [reference for the `#[builder(derive(...))]` attribute](../reference/builder/top-level/derive).

website/guide/limitations.md

@@ -143,7 +143,3 @@ It's possible to place `#[builder]` on top of a `const fn`, but the generated bu
 If you have a strong use case that requires full support for `const`, feel free to [open an issue]. We'll figure something out for sure 🐱.
 
 [open an issue]: https://github.com/elastio/bon/issues
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments

website/guide/optional-members.md

@@ -56,7 +56,7 @@ example().maybe_level(value).call();
 
 ## `#[builder(default)]`
 
-To make a member of non-`Option` type optional you may use the attribute [`#[builder(default)]`](../reference/builder#default). This attribute uses the [`Default`](https://doc.rust-lang.org/stable/std/default/trait.Default.html) trait or the provided expression to assign the default value for the member.
+To make a member of non-`Option` type optional you may use the attribute [`#[builder(default)]`](../reference/builder/member/default). This attribute uses the [`Default`](https://doc.rust-lang.org/stable/std/default/trait.Default.html) trait or the provided expression to assign the default value for the member.
 
 ::: tip
 
@@ -104,8 +104,3 @@ assert_eq!(result, 8);
 ## Conditional building
 
 Now that you know how optional members work you can check out the ["Conditional building" patterns](./patterns/conditional-building) or continue studying other features of `bon` by following the "Next page" link at the bottom.
-
-
-*[Member]: Struct field or a function argument
-*[member]: Struct field or a function argument
-*[members]: Struct fields or function arguments