📎 Auto generate the configuration page configuration.mdx

[ematipico]

Description

The configuration.mdx is updated manually, and this is bothersome because we could actually generate automatically from the rust doc comments relatively easily.

[unvalley]

On this page https://biomejs.dev/reference/configuration , we need to update biome hosted schema version automatically. It's still 1.2.2

[ematipico]

At the moment the page contains good examples, and there's a chance we won't be able to have those examples anymore.

I see two solutions:

• have these examples inside the doc comments
• having a dedicated page for these examples (a guide to the configuration)

[yossydev]

I would like to work on this issue, can you assign me?

[nissy-dev]

I assigned!

[ematipico]

@yossydev I suggest to take a look at workespace_types.rs. It's a file that uses the JSON schema emitted by the configuration, to create TypeScript types.

We could do something similar with the JSON schema, and emit a markdown file instead. The JSON schema should retain the comments, although I don't know if it retains all of them, and if it's able to retain the markdown syntax too.

[yossydev]

@ematipico
Hello! I have one question.

Right now I am trying to read packages/@biomejs/biome/configuration_schema.json and convert it to markdown!

However, the JSON schema defined seems to be different from the current configuration page.
For example,

{
  "$schema": ". /node_modules/@biomejs/biome/configuration_schema.json"
}

does not seem to be defined.

Presumably this is also required? Can I define it myself?

Please check it out at your leisure: 🙇‍♂️

Translated with www.DeepL.com/Translator (free version)

[ematipico]

Hi @yossydev , apologies for not explaining a bit more about what the task is about. This is my fault.

We don't want to read the file configuration_schema.json, but we want to use schemars crate, and extract the information from it.

schemars should create a data structure that contains the information we need. In fact, in workspace_types.rs, we use it programmatically to create TypeScript interfaces.

Here's an example of how you can generate the schema:

biome/crates/biome_service/src/workspace_types.rs

Lines 421 to 433 in c3150e6

	fn of<P, R>(name: &'static str) -> Self
	where
	P: JsonSchema,
	R: JsonSchema,
	{
	let params = SchemaGenerator::from(SchemaSettings::openapi3()).root_schema_for::<P>();
	let result = SchemaGenerator::from(SchemaSettings::openapi3()).root_schema_for::<R>();
	Self {
	name,
	params,
	result,
	}
	}

And this is a function that process the schema and starts generating types

biome/crates/biome_service/src/workspace_types.rs

Line 296 in c3150e6

pub fn generate_type<'a>(

This isn't a beginner task, that was a mistake of mine, apologies for that. 🙇
If you think it's too complex and you don't want to do that, it's completely fine!

[yossydev]

@ematipico
Thanks for the explanation!
Yes, it feels a bit like a heavy issue for me right now...!
Sorry, I would like to ask another person to handle this one!

If there is another issue that I can do, please let me deal with it!

[chansuke]

I'd like to work on this issue 🙇

[ematipico]

Thank you @chansuke , let me know if you have any questions

[chansuke]

@ematipico

I have implemented the auto-generation of configuration.md using schemars. This involves generating a JSON schema from struct Configuration and parsing it into markdown format.

This process requires programmatic parsing of JSON code blocks and lists, as our configuration is extensively described in JSON. For example:

{"anyOf":[{"$ref":"#/definitions/JsonConfiguration"},{"type":"null"}],"description":"Options applied to JSON files.\n\n### `json.parser.allowComments`\n\nEnables parsing of comments in JSON files.\n\n```json title=\"biome.json\" { \"json\": { \"parser\": { \"allowComments\": true } } } ```\n\n### `json.parser.allowTrailingCommas`\n\nEnables parsing of trailing commas in JSON files.\n\n```json title=\"biome.json\" { \"json\": { \"parser\": { \"allowTrailingCommas\": true } } } ```\n\n### `json.formatter.enabled`\n\nEnables Biome's formatter for JSON (and its super languages) files.\n\n> Default: `true`\n\n### `json.formatter.indentStyle`\n\nThe style of indentation for JSON (and its super languages) files. It can be either `\"tab\"` or `\"space\"`.\n\n> Default: `tab`\n\n### `json.formatter.indentSize`\n\nDefines the size of indentation for JSON (and its super languages) files.\n\n> Default: `2`\n\n### `json.formatter.lineEnding`\n\nThe type of line ending for JSON (and its super languages) files: - `lf`, Line Feed only (`\\n`), common on Linux and macOS as well as inside git repos; - `crlf` Carriage Return + Line Feed characters (`\\r\\n`), common on Windows; - `cr` Carriage Return character only (`\\r`), used very rarely.\n\n> Default: `lf`\n\n### `json.formatter.lineWidth`\n\nSpecifies the maximum number of characters on a single line in JSON (and its super languages) files.\n\n> Default: `80`"}

However, there are some notable differences compared to our existing configuration.mdx:

• Order of Items:
  The sequential generation of the document from struct Configuration introduces variations in the order of items.
• JSON Blocks:
  There are some discrepancies in certain JSON blocks.

How do you think about my approach 🙇

[ematipico]

@chansuke

Order of Items:
The sequential generation of the document from struct Configuration introduces variations in the order of items.

I don't mind the order of the items, as long as they don't change if we execute the codegen script multiple times

JSON Blocks:
There are some discrepancies in certain JSON blocks.

I think it's fine, and I think we shouldn't keep all the examples. I think small code snippets should be fine.

I think we should move bigger code snippets like ignore, exclude and extends inside a different page. Maybe a new page where we explain how to set up Biome's configuration. Then, the documentation could have a link to that page.

[chansuke]

@ematipico
Thank you for your reply!

I don't mind the order of the items, as long as they don't change if we execute the codegen script multiple times

Yes, wen can execute the codegen muiltiple times with same result

I think we should move bigger code snippets like ignore, exclude and extends inside a different page

Ok, I will move bigger code snippets from crates/biome_service/src/configuration/mod.rs to new file under crates/biome_service/src/configuration/ directory.

[chansuke]

@ematipico
I've created a dedicated examples page for detailed configuration examples (like ignore, exclude, etc.) and added a link to this page in the main documentation. This approach was chosen as the simplest way to streamline the documentation and reduce its complexity.
How do you think about my approach 🙇

[ematipico]

I'll look into it soon, thank you!

[chansuke]

@ematipico

I rebased my working branch onto the latest commit to finalize my pull request. However, after rebasing with the latest Configuration, I encountered the following error:

   --> xtask/codegen/src/generate_markdown.rs:11:30
    |
11  |     let schema = schema_for!(Configuration);
    |                  ------------^^^^^^^^^^^^^-
    |                  |           |
    |                  |           the trait `JsonSchema` is not implemented for `biome_service::Configuration`
    |                  required by a bound introduced by this call
    |
    = help: the following other types implement trait `JsonSchema`:
              bool
              char
              isize
              i8
              i16
              i32
              i64
              i128
            and 279 others
note: required by a bound in `SchemaGenerator::into_root_schema_for`

To progress, I implemented a temporary fix which allowed me to generate markdown locally again. However, this fix might not be ideal as it bypasses the schemars configuration and could potentially affect other crates.

And now I'm facing the error to derive JsonSchema like below:

error: cannot determine resolution for the derive macro `JsonSchema`
 --> crates/biome_service/src/configuration/css.rs:9:81
  |
9 | #[derive(Clone, Default, Debug, Deserialize, Eq, Partial, PartialEq, Serialize, JsonSchema)]
  |                                                                                 ^^^^^^^^^^
  |
  = note: import resolution is stuck, try simplifying macro imports

Could you provide some feedback on how to resolve these issues 🙏

[ematipico]

@chansuke Thank you for reaching out for help. I pushed a fix in your PR 989f192 (#1028)

Instead of using Configuration, we now have a new struct called PartialConfiguration that automatically created by our Partial macro. :)

biome/crates/biome_service/src/configuration/mod.rs

Line 68 in 763844b

#[derive(Clone, Debug, Default, Deserialize, Eq, Partial, PartialEq, Serialize)]

[chansuke]

@ematipico Thank you!!!!

[chansuke]

@ematipico
I'm formatting json block which is parsed from struct but with generate_bindings, formatting json blocks seems broken and test fails.

Please kindly give me your advice 🙏
Thank you.