Guard with enforce_triplequote_docstring option.

Author: iago-lito

docs/src/formatting_options.md

@@ -64,6 +64,7 @@ If you absolutely must enable them, you may need to run the formatter multiple t
 | [`annotate_untyped_fields_with_any`](@ref options-annotate-untyped-fields-with-any) | ⚠️    | `true`    | `true`      | **`false`** | `true`       | **`false`**   |
 | [`conditional_to_if`](@ref options-conditional-to-if)                               | 🪃 ♻️ | `false`   | `false`     | **`true`**  | `false`      | `false`       |
 | [`disallow_single_arg_nesting`](@ref options-disallow-single-arg-nesting)           | 📐    | `false`   | `false`     | `false`     | **`true`**   | `false`       |
+| [`enforce_triplequote_docstring`](@ref options-enforce-triplequote-docstring)       | ⚠️    | `true`    | `true`      | `true`      | `true`       | `true`        |
 | [`for_in_replacement`](@ref options-for-in-replacement)                             | ♻️    | `"in"`    | `"in"`      | `"in"`      | `"in"`       | `"in"`        |
 | [`force_long_function_def`](@ref options-force-long-function-def)                   | ⚠️    | `false`   | `false`     | `false`     | `false`      | `false`       |
 | [`format_docstrings`](@ref options-format-docstrings)                               | ⚠️    | `false`   | `false`     | `false`     | `false`      | `false`       |
@@ -330,6 +331,14 @@ function_call("String argument")
 {key => value("String value")}
 ```
 
+## [`enforce_triplequote_docstring`](@id options-enforce-triplequote-docstring)
+
+Default: `true`
+
+Ensure that docstrings always use triple `"""` quoting marks.
+
+Only useful if [`format_docstrings`](@ref options-format-docstrings) is on.
+
 ## [`for_in_replacement`](@id options-for-in-replacement)
 
 Can be used when [`always_for_in`](@ref options-always-for-in) is `true` to replace the default `in` with `∈` (`\\in`),

src/format_docstring.jl

@@ -51,7 +51,7 @@ end
 function format_docstring(style::AbstractStyle, state::State, text::AbstractString)
     state_indent = state.indent
     start_boundary = findfirst(!=('"'), text)
-    is_triple_quoted = let
+    is_triple_quoted = state.opts.enforce_triplequote_docstring || let
         # Assuming well-formedness, the string is triple-quoted iif
         # the chars after/before (o)pening/(c)losing quotes are also quotes.
         o, c = map(f -> f(==('"'), text), (findfirst, findlast))

src/options.jl

@@ -37,6 +37,7 @@ Base.@kwdef struct Options{T<:_Unset}
     annotate_untyped_fields_with_any::Union{T,Bool} = true
     conditional_to_if::Union{T,Bool} = false
     disallow_single_arg_nesting::Union{T,Bool} = false
+    enforce_triplequote_docstring::Union{T,Bool} = true
     for_in_replacement::Union{T,String} = "in"
     force_long_function_def::Union{T,Bool} = false
     format_docstrings::Union{T,Bool} = false

test/argparse.jl

@@ -268,6 +268,8 @@ using JuliaFormatter: DefaultStyle, YASStyle, BlueStyle, SciMLStyle, MinimalStyl
             @test parse_args(["--conditional-to-if=false"]).config.options.conditional_to_if == false
             @test parse_args(["--disallow-single-arg-nesting=true"]).config.options.disallow_single_arg_nesting == true
             @test parse_args(["--disallow-single-arg-nesting=false"]).config.options.disallow_single_arg_nesting == false
+            @test parse_args(["--enforce-triplequote-docstring=true"]).config.options.enforce_triplequote_docstring == true
+            @test parse_args(["--enforce-triplequote-docstring=false"]).config.options.enforce_triplequote_docstring == false
             @test parse_args(["--force-long-function-def=true"]).config.options.force_long_function_def == true
             @test parse_args(["--force-long-function-def=false"]).config.options.force_long_function_def == false
             @test parse_args(["--format-docstrings=true"]).config.options.format_docstrings == true

test/options.jl

@@ -714,7 +714,9 @@ end
 
     @testset "issue 1203" begin
 
-        # Use let blocks to check indentation.
+        opts = (; format_docstrings = true)
+
+        # (use begin blocks to check indentation)
         triple = """
         begin
             \"""
@@ -731,9 +733,13 @@ end
         end
         """
 
-        test_format(triple, triple; format_docstrings=true)
-        test_format(single, triple; format_docstrings=true)
-        test_format(single, single; format_docstrings=true)
+        # Normalize to triple by default.
+        test_format(triple, triple; opts...)
+        test_format(single, triple; opts...)
+
+        # Unless we opt out.
+        opts = (; enforce_triplequote_docstring = false, opts...)
+        test_format(single, single; opts...)
 
         # Not exactly good taste, but the option leaves it alone as promised.
         single_multiline = """
@@ -743,7 +749,7 @@ end
             f() = 0
         end
         """
-        test_format(single_multiline, single_multiline; format_docstrings=true)
+        test_format(single_multiline, single_multiline; opts...)
 
         # Still drop trailing whitespace on the first line (#667).
         test_format(
@@ -761,7 +767,7 @@ end
                 f() = 0 # Can somebody help explain why newlines are being inserted here?
             end
             """,
-            ; format_docstrings=true)
+            ; opts...)
 
     end