docs v3 (#1118)

New documentation structure

---------

Co-authored-by: Vaibhav Gupta <[email protected]>
Co-authored-by: Antonio Sarosi <[email protected]>

docs/README.md

@@ -1,22 +1 @@
-# Fern Configuration
-
-View the documentation [here](https://boundary.docs.buildwithfern.com).
-
-## Updating your Docs
-
-### Local Development server
-
-To run a local development server with hot-reloading you can run the following command
-
-```sh
-fern docs dev
-```
-
-### Hosted URL 
-
-Documentation is automatically updated when you push to main via the `fern generate` command. 
-
-```sh
-npm install -g fern-api # only required once
-fern generate --docs
-```
+If you're looking for docs, go to the [fern/](../fern) directory

docs/old/01-guide/04-baml-basics/switching-llms.mdx

@@ -0,0 +1,56 @@
+---
+title: Switching LLMs
+---
+
+Switch LLMs using the `client` property. You can use the shorthand form, or the longer form with a named client.
+
+The shorthand form is `<provider>/<model>`:
+
+which uses ANTHROPIC_API_KEY or OPENAI_API_KEY environment variables as the defaults.
+
+```rust BAML
+function MakeHaiku(topic: string) -> string {
+  client "openai/gpt-4o" // or anthropic/claude-3-5-sonnet-20241022
+  prompt #"
+    Write a haiku about {{ topic }}.
+  "#
+}
+```
+
+The longer form uses a named client, and supports adding any parameters supported by the provider or changing the temperature, top_p, etc.
+
+```rust BAML
+client<llm> MyClient {
+  provider "openai"
+  options {
+    model "gpt-4o"
+    api_key env.OPENAI_API_KEY
+    // other params like temperature, top_p, etc.
+    temperature 0.5
+    base_url "https://my-custom-endpoint.com/v1"
+    // add headers
+    headers {
+      "anthropic-beta" "prompt-caching-2024-07-31"
+    }
+  }
+
+}
+
+function MakeHaiku(topic: string) -> string {
+  client MyClient
+  prompt #"
+    Write a haiku about {{ topic }}.
+  "#
+}
+```
+
+Consult the [provider documentation](#fields) for a list of supported providers
+and models, the default options, and setting [retry policies](/docs/reference/retry-policy).
+
+<Tip>
+If you want to specify which client to use at runtime, in your Python/TS/Ruby code,
+you can use the [client registry](/docs/calling-baml/client-registry) to do so.
+
+This can come in handy if you're trying to, say, send 10% of your requests to a
+different model.
+</Tip>

docs/old/README.md

@@ -0,0 +1,22 @@
+# Fern Configuration
+
+View the documentation [here](https://boundary.docs.buildwithfern.com).
+
+## Updating your Docs
+
+### Local Development server
+
+To run a local development server with hot-reloading you can run the following command
+
+```sh
+fern docs dev
+```
+
+### Hosted URL 
+
+Documentation is automatically updated when you push to main via the `fern generate` command. 
+
+```sh
+npm install -g fern-api # only required once
+fern generate --docs
+```

docs/docs/calling-baml/dynamic-types.mdx → docs/old/docs/calling-baml/dynamic-types.mdx

@@ -183,10 +183,11 @@ async def run():
   tb = TypeBuilder()
   hobbies_enum = tb.add_enum("Hobbies")
   hobbies_enum.add_value("Soccer")
-  hobbies_enum.add_value("Reading")
+  hobbies_enum.add_value("Reading").description("A hobby of reading")
 
   address_class = tb.add_class("Address")
-  address_class.add_property("street", tb.string())
+  # You can also add descriptions to your types
+  address_class.add_property("street", tb.string()).description("The street address")
 
   tb.User.add_property("hobby", hobbies_enum.type().optional())
   tb.User.add_property("address", address_class.type().optional())
@@ -204,10 +205,10 @@ async function run() {
   const tb = new TypeBuilder()
   const hobbiesEnum = tb.addEnum('Hobbies')
   hobbiesEnum.addValue('Soccer')
-  hobbiesEnum.addValue('Reading')
+  hobbiesEnum.addValue('Reading').description('A hobby of reading')
 
   const addressClass = tb.addClass('Address')
-  addressClass.addProperty('street', tb.string())
+  addressClass.addProperty('street', tb.string()).description('The street address')
 
 
   tb.User.addProperty('hobby', hobbiesEnum.type().optional())

docs/docs/calling-baml/multi-modal.mdx → docs/old/docs/calling-baml/multi-modal.mdx

@@ -5,7 +5,7 @@ slug: docs/calling-baml/multi-modal
 
 ## Multi-modal input
 
-### Images 
+### Image
 Calling a BAML function with an `image` input argument type (see [image types](../snippets/supported-types.mdx)).
 
 The `from_url` and `from_base64` methods create an `Image` object based on input type.

docs/docs/calling-baml/validations.mdx → docs/old/docs/calling-baml/validations.mdx

@@ -42,7 +42,7 @@ function NextInt8(a: int) -> int @assert(ok_int8, {{ this >= -128 and this < 127
 
 ### Using `@assert` with `Union` Types
 
-Note that when using [`Unions`](../snippets/supported-types.mdx#union-), it is
+Note that when using [`Unions`](/ref/baml/types#union-), it is
 crucial to specify where the `@assert` attribute is applied within the union
 type, as it is not known until runtime which type the value will be.
 
@@ -83,7 +83,7 @@ regular expressions.
 In the future, we plan to support shorthand syntax for common assertions to make
 writing them easier.
 
-For now, see our [Jinja cookbook / guide](../snippets/prompt-syntax/what-is-jinja.mdx)
+For now, see our [Jinja cookbook / guide](/ref/prompt-syntax/what-is-jinja)
 or the [Minijinja filters docs](https://docs.rs/minijinja/latest/minijinja/filters/index.html#functions)
 for more information on writing expressions.
 

docs/docs/snippets/clients/overview.mdx → docs/old/docs/snippets/clients/overview.mdx

@@ -20,7 +20,7 @@ client<llm> MyClient {
   provider "openai"
   options {
     model "gpt-4o"
-    // api_key defaults to env.OPENAI_API_KEY
+    api_key env.OPENAI_API_KEY
   }
 }
 

docs/docs/snippets/functions/function-calling.mdx → docs/old/docs/snippets/functions/function-calling.mdx

@@ -55,9 +55,9 @@ function UseTool(user_message: string) -> (WeatherAPI | MyOtherAPI)[] {
 ```
 
 ## Function-calling APIs vs Prompting
-Injecting your function schemas into the prompt, as BAML does, outperforms function-calling across all benchmarks for major providers (see [Berkeley's Function-calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html), where "Prompt" outperforms "FC").
+Injecting your function schemas into the prompt, as BAML does, outperforms function-calling across all benchmarks for major providers ([see our Berkeley FC Benchmark results with BAML](https://www.boundaryml.com/blog/sota-function-calling?q=0)).
 
 Keep in mind that "JSON mode" is nearly the same thing as "prompting", but it enforces the LLM response is ONLY a JSON blob.
 BAML does not use JSON mode since it allows developers to use better prompting techniques like chain-of-thought, to allow the LLM to express its reasoning before printing out the actual schema. BAML's parser can find the json schema(s) out of free-form text for you.
 
-BAML may support native function-calling APIs in the future (please let us know more about your use-case so we can prioritize accordingly)
+BAML will support native function-calling APIs in the future (please let us know more about your use-case so we can prioritize accordingly)

engine/baml-runtime/src/cli/init.rs

@@ -19,7 +19,7 @@ pub struct InitArgs {
 
     #[arg(
         long,
-        help = r#"The OpenAPI client generator to run, if --client-type=openapi.
+        help = r#"The OpenAPI client generator to run, if --client-type=rest/openapi.
 Examples: "go", "java", "php", "ruby", "rust".  See full list at https://github.com/OpenAPITools/openapi-generator#overview."#
     )]
     openapi_client_type: Option<String>,

fern/01-guide/01-editors/cursor.mdx

@@ -0,0 +1,8 @@
+---
+title: Cursor
+---
+Refer to the [Cursor Extension Installation Guide](https://www.cursor.com/how-to-install-extension) to install the extension in Cursor.
+
+<Warning>
+You may need to update BAML extension manually using the process above. Auto-update does not seem to be working well for many extensions in Cursor.
+</Warning>

fern/01-guide/01-editors/others.mdx

@@ -0,0 +1,15 @@
+We don't currently have any tier support for any other editors.
+
+* JetBrains IDEs
+* Helix
+* Zed
+* Vim
+* Emacs
+* Sublime Text
+* Atom
+
+
+Since the extension is a language server, we can technically pull out the language server and syntax highlighter and support any editor supporting the language server protocol.
+If you're interested in contributing to the project and supporting another editor, [please reach out](/contact).
+
+An alternative is to edit your files in our [Playground](https://www.promptfiddle.com/), and copy the code into your editor, but we recommend using VSCode to edit BAML files for now.

fern/01-guide/01-editors/vscode.mdx

@@ -0,0 +1,65 @@
+We provide a BAML VSCode extension:     https://marketplace.visualstudio.com/items?itemName=Boundary.baml-extension
+
+
+
+| Feature | Supported |
+|---------|-----------|
+| Syntax highlighting for BAML files | ✅ |
+| Code snippets for BAML | ✅ |
+| LLM playground for testing BAML functions | ✅ |
+| Jump to definition for BAML files | ✅ |
+| Jump to definition between Python/TS files and BAML files | ✅ |
+| Auto generate `baml_client` on save | ✅ |
+| BAML formatter | ❌ |
+
+## Opening BAML Playground
+
+Once you open a `.baml` file, in VSCode, you should see a small button over every BAML function: `Open Playground`.
+
+<img src="/assets/vscode/code-lens.png" />
+
+Or type `BAML Playground` in the VSCode Command Bar (`CMD + Shift + P` or `CTRL + Shift + P`) to open the playground.
+
+<img src="/assets/vscode/open-playground.png" />
+
+## Setting Env Variables
+
+Click on the `Settings` button in top right of the playground and set the environment variables.
+
+It should have an indicator saying how many unset variables are there.
+
+<img src="/assets/vscode/playground-preview.png" />
+
+The playground should persist the environment variables between closing and opening VSCode.
+
+<Tip>
+  You can set environment variables lazily. If anything is unset you'll get an error when you run the function.
+</Tip>
+
+<Info>
+  Environment Variables are stored in VSCode's local storage! We don't save any additional data to disk, or send them across the network.
+</Info>
+
+
+## Running Tests
+
+- Click on the `Run All Tests` button in the playground.
+
+- Press the `▶️` button next to an individual test case to run that just that test case.
+
+
+## Switching Functions
+
+The playground will automatically switch to the function you're currently editing.
+
+To manually change it, click on the current function name in the playground (next to the dropdown) and search for your desired function.
+
+## Switching Test Cases
+
+The test case with the highlighted background is the currently rendered test case. Clicking on a different test case will render that test case.
+
+<img src="/assets/vscode/test-cases.png" />
+
+You can toggle between seeing the results of all test cases or all test cases for the current function.
+
+<img src="/assets/vscode/test-case-buttons.png" />