Streamline docsite

Author: ianks

Rakefile

@@ -79,6 +79,9 @@ desc "Pretty the files"
 task :fmt do
   sh "cargo fmt"
   sh "bundle exec standardrb --fix" if RUBY_VERSION >= "2.6.0"
+  Dir.chdir("docsite") do
+    sh "npm run fmt"
+  end
   sh "npx prettier --write $(git ls-files '*.yml')"
   md_files = `git ls-files '*.md'`.split("\n").select { |f| File.exist?(f) }
   sh "npx", "prettier", "--write", "--print-width=120", "--prose-wrap=always", *md_files

docsite/.prettierignore

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+
+# Build artifacts
+build/
+.docusaurus/
+
+# Lockfiles
+package-lock.json
+yarn.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store

docsite/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "printWidth": 120,
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "proseWrap": "preserve"
+}

docsite/docs/api-reference/rb-sys-features.mdx

@@ -1,92 +1,52 @@
 ---
 id: rb-sys-features
-title: rb-sys Crate Features
+title: Crate `rb-sys`
 ---
 
-# rb-sys Crate Features
+# Crate `rb-sys`
 
-The `rb-sys` crate provides battle-tested Rust bindings for the Ruby C API. It uses the
-[`rust-bindgen`](https://github.com/rust-lang/rust-bindgen) crate to generate bindings from the `ruby.h` header.
+The `rb-sys` crate provides low-level Rust bindings for the Ruby C API, generated directly from `ruby.h` headers.
 
-## Usage Notice
+## Constraints
 
-This is a very low-level library. If you are looking to write a gem in Rust, you should probably use the
-[Magnus](https://github.com/matsadler/magnus) crate with the `rb-sys-interop` feature, which provides a higher-level,
-more ergonomic API.
+- **Direct `rb-sys`:** Use for raw, `unsafe` access to `libruby`.
+- **Gem Development:** For most gem development, prefer higher-level libraries (e.g., [Magnus](https://github.com/matsadler/magnus) with `rb-sys` feature). See [Development Approaches](../development-approaches.mdx).
+- **Embedding Ruby:** Use `rb-sys` with the `link-ruby` feature.
 
-If you need raw/unsafe bindings to libruby, then this crate is for you!
+## Crate Features
 
-## Writing a Ruby Gem
+The following features can be enabled in your `Cargo.toml`.
 
-Ruby gems require boilerplate to be defined to be usable from Ruby. `rb-sys` makes this process painless by doing the
-work for you. Simply enable the `gem` feature:
+| Feature                    | Description                                                                      | Default |
+| :------------------------- | :------------------------------------------------------------------------------- | :------ |
+| `gem`                      | Configures the crate for building a Ruby gem (e.g., does not link `libruby`).    | ✅      |
+| `link-ruby`                | Links `libruby` for embedding the Ruby VM in a Rust binary.                      |         |
+| `ruby-static`              | Statically links `libruby`. Can also be set with the `RUBY_STATIC=true` env var. |         |
+| `global-allocator`         | Reports Rust memory allocations to the Ruby GC. Recommended for gems.            |         |
+| `stable-api`               | Uses Ruby's C-level stable API if available for your Ruby version.               |         |
+| `bindgen-rbimpls`          | Includes internal Ruby implementation types in the generated bindings.           |         |
+| `bindgen-deprecated-types` | Includes deprecated Ruby functions and types in the bindings.                    |         |
 
-```toml
-[dependencies]
-rb-sys = "0.9"
-```
+## Usage Examples
 
-Under the hood, this ensures the crate does not link libruby (unless on Windows) and defines a `ruby_abi_version`
-function for Ruby 3.2+.
+### Ruby Gem Integration
 
-## Embedding libruby in Your Rust App
-
-:::important If you are authoring a Ruby gem, you do not need to enable this feature. :::
-
-If you need to link libruby (i.e., you are initializing a Ruby VM in your Rust code), you can enable the `link-ruby`
-feature:
+Enable the `gem` feature (default) and `global-allocator` for memory reporting.
 
 ```toml
 [dependencies]
-rb-sys = { version = "0.9", features = ["link-ruby"] }
+rb-sys = { version = "0.9", features = ["global-allocator"] }
 ```
 
-## Static libruby
+### Embedding Ruby VM
 
-You can also force static linking of libruby:
+Enable the `link-ruby` feature to embed a Ruby VM.
 
 ```toml
 [dependencies]
-rb-sys = { version = "0.9", features = ["ruby-static"] }
-```
-
-Alternatively, you can set the `RUBY_STATIC=true` environment variable.
-
-## Available Features
-
-The `rb-sys` crate provides several features that can be enabled in your `Cargo.toml`:
-
-| Feature                    | Description                                                     |
-| -------------------------- | --------------------------------------------------------------- |
-| `global-allocator`         | Report Rust memory allocations to the Ruby GC (_recommended_)   |
-| `ruby-static`              | Link the static version of libruby                              |
-| `link-ruby`                | Link libruby (typically used for embedding, not for extensions) |
-| `bindgen-rbimpls`          | Include the Ruby impl types in bindings                         |
-| `bindgen-deprecated-types` | Include deprecated Ruby methods in bindings                     |
-| `gem`                      | Set up the crate for use in a Ruby gem (default feature)        |
-| `stable-api`               | Use the stable API (C level) if available for your Ruby version |
-
-## Example Cargo.toml
-
-```toml
-[dependencies]
-rb-sys = { version = "0.9", features = ["global-allocator", "stable-api"] }
+rb-sys = { version = "0.9", features = ["link-ruby"] }
 ```
 
 ## Ruby Version Compatibility
 
-`rb-sys` is compatible with Ruby 2.6 and later. The crate detects the Ruby version at compile time and adapts the
-bindings accordingly.
-
-For Ruby 3.2 and later, `rb-sys` provides a `ruby_abi_version` function that is required for native extensions.
-
-## Integration with Magnus
-
-If you're building a Ruby extension, it's recommended to use the [Magnus](https://github.com/matsadler/magnus) crate on
-top of `rb-sys`. Magnus provides a high-level, safe API for interacting with Ruby:
-
-```toml
-[dependencies]
-magnus = { version = "0.7", features = ["rb-sys"] }
-rb-sys = "0.9"
-```
+`rb-sys` is compatible with Ruby 2.6+. It detects the Ruby version at compile time and generates appropriate bindings. Ruby 3.2+ requires `ruby_abi_version` function, which `rb-sys` provides automatically.

docsite/docs/api-reference/rb-sys-gem-config.mdx

@@ -1,110 +1,63 @@
 ---
 id: rb-sys-gem-config
-title: rb_sys Gem Configuration
+title: Gem Configuration
 ---
 
-# rb_sys Gem Configuration
+# Gem Configuration
 
-The `rb_sys` gem makes it easy to build native Ruby extensions in Rust. It interoperates with existing Ruby native
-extension toolchains (i.e., `rake-compiler`) to make testing, building, and cross-compilation of gems easy.
+The `rb_sys` Ruby gem provides helpers for building Rust-based extensions, integrating with standard tools like `rake-compiler`.
 
-## RbSys::ExtensionTask
+## `RbSys::ExtensionTask`
 
-This gem provides a `RbSys::ExtensionTask` class that can be used to build a Ruby extension in Rust. It's a thin wrapper
-around `Rake::ExtensionTask` that provides sane defaults for building Rust extensions.
+Define how your Rust extension is built within your `Rakefile` using `RbSys::ExtensionTask`.
 
 ```ruby
 # Rakefile
-
 require "rb_sys/extensiontask"
 
 GEMSPEC = Gem::Specification.load("my_gem.gemspec")
 
 RbSys::ExtensionTask.new("my-crate-name", GEMSPEC) do |ext|
   ext.lib_dir = "lib/my_gem"
-
-  # If you want to use `rb-sys-dock` for cross-compilation:
-  ext.cross_compile = true
+  ext.cross_compile = true # Enable cross-compilation with rb-sys-dock.
 end
 ```
 
-## create_rust_makefile
+## `create_rust_makefile`
 
-The gem provides a simple helper to build a Ruby-compatible Makefile for your Rust extension:
+Generate a Ruby-compatible `Makefile` for your Rust extension in your `extconf.rb`.
 
 ```ruby
-# ext/rust_reverse/extconf.rb
-
-# We need to require mkmf *first* since `rake-compiler` injects code here for cross compilation
+# ext/my_gem/extconf.rb
 require "mkmf"
 require "rb_sys/mkmf"
 
-create_rust_makefile("rust_reverse") do |r|
-  # Create debug builds in dev. Make sure that release gems are compiled with
-  # `RB_SYS_CARGO_PROFILE=release` (optional)
-  r.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", :dev).to_sym
-
-  # Can be overridden with `RB_SYS_CARGO_FEATURES` env var (optional)
-  r.features = ["test-feature"]
-
-  # You can add whatever env vars you want to the env hash (optional)
-  r.env = {"FOO" => "BAR"}
-
-  # If your Cargo.toml is in a different directory, you can specify it here (optional)
-  r.ext_dir = "."
-
-  # Extra flags to pass to the $RUSTFLAGS environment variable (optional)
-  r.extra_rustflags = ["--cfg=some_nested_config_var_for_crate"]
-
-  # Force a rust toolchain to be installed via rustup (optional)
-  # You can also set the env var `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN=true`
-  r.force_install_rust_toolchain = "stable"
-
-  # Clean up the target/ dir after `gem install` to reduce bloat (optional)
-  r.clean_after_install = false # default: true if invoked by rubygems
-
-  # Auto-install Rust toolchain if not present on "gem install" (optional)
-  r.auto_install_rust_toolchain = false # default: true if invoked by rubygems
+create_rust_makefile("my_gem") do |r|
+  r.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", :dev).to_sym # Cargo build profile (:dev or :release).
+  r.features = ["a-feature"] # Comma-separated list of Cargo features.
+  r.extra_rustflags = ["--cfg=some_config_flag"] # Extra flags for $RUSTFLAGS.
+  r.ext_dir = "." # Directory containing Cargo.toml, relative to extconf.rb.
 end
 ```
 
 ## Environment Variables
 
-The `rb_sys` gem respects several environment variables that can modify its behavior:
-
-| Environment Variable                  | Description                                         |
-| ------------------------------------- | --------------------------------------------------- |
-| `RB_SYS_CARGO_PROFILE`                | Set the Cargo profile (i.e., `release` or `dev`)    |
-| `RB_SYS_CARGO_FEATURES`               | Comma-separated list of Cargo features to enable    |
-| `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN` | Force installation of a Rust toolchain              |
-| `RUBY_STATIC`                         | Force static linking of libruby if set to `true`    |
-| `LIBCLANG_PATH`                       | Path to libclang if it can't be found automatically |
-
-## Tips and Tricks
-
-- When using `rake-compiler` to build your gem, you can use the `RB_SYS_CARGO_PROFILE` environment variable to set the
-  Cargo profile (i.e., `release` or `dev`).
-
-- You can pass Cargo arguments to `rake-compiler` like so: `rake compile -- --verbose`
+These environment variables control the `rb_sys` build process.
 
-- It's possible to force an installation of a Rust toolchain by setting the `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN`
-  environment variable. This will install [rustup](https://rustup.rs/) and [cargo](https://crates.io/) in the build
-  directory, so the end user does not have to have Rust pre-installed. Ideally, this should be a last resort, as it's
-  better to already have the toolchain installed on your system.
+| Environment Variable                  | Description                                              |
+| :------------------------------------ | :------------------------------------------------------- |
+| `RB_SYS_CARGO_PROFILE`                | Set the Cargo profile (e.g., `release` or `dev`).        |
+| `RB_SYS_CARGO_FEATURES`               | Comma-separated list of Cargo features to enable.        |
+| `RB_SYS_FORCE_INSTALL_RUST_TOOLCHAIN` | Set to `true` to force installation of a Rust toolchain. |
+| `RUBY_STATIC`                         | Set to `true` to force static linking of `libruby`.      |
+| `LIBCLANG_PATH`                       | Path to `libclang` if it can't be found automatically.   |
+| `RB_SYS_VERBOSE_BUILD`                | Set to `true` to enable verbose output during the build. |
 
 ## Troubleshooting
 
-### Libclang Issues
-
-If you see an error like this:
-
-```
-thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"'
-```
+### `libclang` Not Found
 
-This means that bindgen is having issues finding a usable version of libclang. An easy way to fix this is to install the
-[`libclang` gem](https://github.com/oxidize-rb/libclang-rb), which will install a pre-built version of libclang for you.
-`rb_sys` will automatically detect this gem and use it.
+If `libclang` is not found during `bindgen` execution, add the `libclang` gem to your `Gemfile`.
 
 ```ruby
 # Gemfile