DOC: fix set_options rendering by documenting defaults explicitly

[dolliecoder]

This PR fixes the documentation rendering issue for set_options by applying the workaround discussed in #10832.

Inline set/tuple defaults in the parameter list are replaced with optional, and default values and allowed options are documented explicitly in the parameter descriptions. This avoids relying on napoleon to render tuple defaults while preserving all existing information.

This is a documentation-only change; no behavior or API changes are made.

Checklist

Closes #10832

Tests added (not applicable — documentation-only change)

User visible changes (including notable bug fixes) are documented in whats-new.rst (not applicable — docs formatting fix only)

New functions/methods are listed in api.rst (not applicable — no new APIs)

[dolliecoder]

The Read the Docs build failed due to excessive memory consumption during the docs environment setup (pixi install -e doc).

This appears to be an RTD infrastructure issue rather than a documentation error introduced by this PR. Happy to adjust if you’d like me to make any changes.

[keewis]

Thanks for picking this up, @dolliecoder.

#10832 was only about netcdf_engine_order, which had a list of string as a default value (which you changed, so that's great).

However, could restore the value sets (e.g. {v1, v2, v3}), please? Those are rendered properly, and it is a bit easier to find the values that way. The other changes are nice, too, so I've added an example of what I would restore below.

[keewis]

the RTD build was flaky, it succeeded on the second try

[dolliecoder]

@keewis Thanks! I've restored the value-set formatting and limited the changes strictly to netcdf_engine_order. Let me know if this now matches expectations.

[keewis]

not quite, what I meant was to put the value-set in the place where you have optional right now. With that, the entire part would become something like:

    arithmetic_compat: {"identical", "equals", "broadcast_equals", "no_conflicts", "override", "minimal"}, default: "minimal"
        How to compare non-index coordinates of the same name for potential
        conflicts when performing binary operations. (For the alignment of index
        coordinates in binary operations, see `arithmetic_join`.)

        Allowed values are:

        - ``"identical"``: all values, dimensions and attributes of the coordinates
          must be the same.
        - ``"equals"``: all values and dimensions of the coordinates must be the
          same.
        - ``"broadcast_equals"``: all values of the coordinates must be equal after
          broadcasting to ensure common dimensions.
        - ``"no_conflicts"``: only values which are not null in both coordinates
          must be equal. The returned coordinate then contains the combination
          of all non-null values.
        - ``"override"``: skip comparing and take the coordinates from the first
          operand.
        - ``"minimal"``: drop conflicting coordinates.

(and similarly for all the other sections except netcdf_engine_order)

[dolliecoder]

@

not quite, what I meant was to put the value-set in the place where you have optional right now. With that, the entire part would become something like:

    arithmetic_compat: {"identical", "equals", "broadcast_equals", "no_conflicts", "override", "minimal"}, default: "minimal"
        How to compare non-index coordinates of the same name for potential
        conflicts when performing binary operations. (For the alignment of index
        coordinates in binary operations, see `arithmetic_join`.)

        Allowed values are:

        - ``"identical"``: all values, dimensions and attributes of the coordinates
          must be the same.
        - ``"equals"``: all values and dimensions of the coordinates must be the
          same.
        - ``"broadcast_equals"``: all values of the coordinates must be equal after
          broadcasting to ensure common dimensions.
        - ``"no_conflicts"``: only values which are not null in both coordinates
          must be equal. The returned coordinate then contains the combination
          of all non-null values.
        - ``"override"``: skip comparing and take the coordinates from the first
          operand.
        - ``"minimal"``: drop conflicting coordinates.

(and similarly for all the other sections except netcdf_engine_order)

thanks for the suggestions .I have applied the changes
if anything else needs to be adjusted please let me know.

[dolliecoder]

@keewis Hi, Please let me know if any additional changes are required from my side.
Happy to refine this further.