Undeprecate ArrowWriter::into_serialized_writer and add docs

[alamb]

Which issue does this PR close?

We generally require a GitHub issue to be filed for all bug fixes and enhancements and this helps us generate change logs for our releases. You can link an issue to this PR using the GitHub syntax.

• Related to Release arrow-rs / parquet Major version 57.0.0 (October 2025) #7835

Rationale for this change

While testing the arrow 57 upgrade in DataFusion I found a few things that need to be fixed
in parquet-rs.

• [WIP] Upgrade to arrow/parquet 57.0.0 datafusion#17888

One was that the method ArrowWriter::into_serialized_writer was deprecated, (which I know I suggested in #8389 🤦 ). However, when testing it turns out that the constructor of SerializedFileWriter does a lot of work (like creating the parquet schema from the arrow schema and messing with metadata)

arrow-rs/parquet/src/arrow/arrow_writer/mod.rs

Lines 230 to 263 in c4f0fc1

	let mut props = options.properties;
	let schema = if let Some(parquet_schema) = options.schema_descr {
	parquet_schema.clone()
	} else {
	let mut converter = ArrowSchemaConverter::new().with_coerce_types(props.coerce_types());
	if let Some(schema_root) = &options.schema_root {
	converter = converter.schema_root(schema_root);
	}
	converter.convert(&arrow_schema)?
	};
	if !options.skip_arrow_metadata {
	// add serialized arrow schema
	add_encoded_arrow_schema_to_metadata(&arrow_schema, &mut props);
	}
	let max_row_group_size = props.max_row_group_size();
	let props_ptr = Arc::new(props);
	let file_writer =
	SerializedFileWriter::new(writer, schema.root_schema_ptr(), Arc::clone(&props_ptr))?;
	let row_group_writer_factory =
	ArrowRowGroupWriterFactory::new(&file_writer, arrow_schema.clone());
	Ok(Self {
	writer: file_writer,
	in_progress: None,
	arrow_schema,
	row_group_writer_factory,
	max_row_group_size,
	})

Creating a RowGroupWriterFactory directly would involve a bunch of code duplication

What changes are included in this PR?

So let's not deprecate this method for now and instead add some additional docs to guide people to the right lace

Are these changes tested?

I tested manually upstream

Are there any user-facing changes?

If there are user-facing changes then we may require documentation to be updated before approving the PR.

If there are any breaking changes to public APIs, please call them out.

[alamb]

I tried to drop a few breadcrumbs to find @adamreeve 's new example in #8582

[adamreeve]

ArrowRowGroupWriter is actually not public and not used in the ArrowColumnWriter example, so this last sentence might be a little confusing.

(ArrowRowGroupWriterFactory is internally used to create ArrowRowGroupWriters, but publicly it only exposes the ability to create a Vec<ArrowColumnWriter>. If I was starting this again from scratch I might have named things a little differently...)

[alamb]

Thanks -- I tried to improve the comments in 619210d

[alamb]

Thank you @adamreeve and @mbrobbel