[Docs] versionadded directive used incorrectly in Columnar Format docs

[mootari]

Describe the bug, including details regarding any error messages, version, and platform.

The page Arrow Columnar Format (source) use Sphinx' versionadded directive to annotate when a particular section was introduced.

However, the directive expects only the first argument to be the version and treats the remainder as brief explanation, resulting in the following rendered output:

New in version Arrow: Columnar Format 1.3

Component(s)

Documentation

[raulcd]

Thanks for opening the issue.

We have two different versions, the format version and the library version, see:
https://arrow.apache.org/docs/19.0/format/Versioning.html#format-versioning-and-stability

I think having this as a comment for the format spec is expected. It looks like this:

What would be your expectation?

[raulcd]

cc @AlenkaF

[mootari]

What would be your expectation?

I'd either expect

New in version Arrow Columnar Format 1.3

or (to account for the directive's limitations)

New in version 1.3

The way it's currently formatted makes "Arrow" appear like a version placeholder, and the description suggests that "Columnar Format 1.3" is the thing being introduced (which may be technically correct but is arguably not the intended message).

If the extended specifier is needed, then maybe versionadded is not a good fit here?

[raulcd]

Thanks for the clarification, that makes sense to me now, sorry I wasn't really understanding the issue you were raising.

[AlenkaF]

Thanks for additional explanation, I needed it also =) I think substituting .. versionadded:: with New in version in format/Columnar.rst makes sense. It is not used elsewhere as far as I can tell.

[mootari]

Apologies for the initial lack of detail, I'll keep that in mind for future issues. 🙏🏻

[kou]

We may be able to use .. info:: New in version Arrow Columnar Format 1.4 for this.

[AlenkaF]

@mootari are you interested in submitting a PR?

[mootari]

@AlenkaF As far as I can tell I'd have to set up everything to build the docs so that I can verify the change. I'm afraid that doesn't seem like time well spent to me for a four-lines change if the same thing can be accomplished by y'all in a matter of minutes. 😅

[AlenkaF]

That makes sense! 😄 If you're interested, you can also make the change directly in the GitHub UI using the edit button (probably from your fork) on the source page. The CI and docs preview build will then automatically verify the result.