@@ -27,7 +27,7 @@ use ruff_linter::settings::types::{
2727} ;
2828use ruff_linter:: { warn_user_once, RuleSelector } ;
2929use ruff_macros:: { CombineOptions , OptionsMetadata } ;
30- use ruff_python_formatter:: QuoteStyle ;
30+ use ruff_python_formatter:: { DocstringCodeLineWidth , QuoteStyle } ;
3131
3232use crate :: settings:: LineEnding ;
3333
@@ -2896,6 +2896,156 @@ pub struct FormatOptions {
28962896 "#
28972897 ) ]
28982898 pub line_ending : Option < LineEnding > ,
2899+
2900+ /// Whether to format code snippets in docstrings.
2901+ ///
2902+ /// When this is enabled, Python code examples within docstrings are
2903+ /// automatically reformatted.
2904+ ///
2905+ /// For example, when this is enabled, the following code:
2906+ ///
2907+ /// ```python
2908+ /// def f(x):
2909+ /// """
2910+ /// Something about `f`. And an example in doctest format:
2911+ ///
2912+ /// >>> f( x )
2913+ ///
2914+ /// Markdown is also supported:
2915+ ///
2916+ /// ```py
2917+ /// f( x )
2918+ /// ```
2919+ ///
2920+ /// As are reStructuredText literal blocks::
2921+ ///
2922+ /// f( x )
2923+ ///
2924+ ///
2925+ /// And reStructuredText code blocks:
2926+ ///
2927+ /// .. code-block:: python
2928+ ///
2929+ /// f( x )
2930+ /// """
2931+ /// pass
2932+ /// ```
2933+ ///
2934+ /// ... will be reformatted (assuming the rest of the options are set to
2935+ /// their defaults) as:
2936+ ///
2937+ /// ```python
2938+ /// def f(x):
2939+ /// """
2940+ /// Something about `f`. And an example in doctest format:
2941+ ///
2942+ /// >>> f(x)
2943+ ///
2944+ /// Markdown is also supported:
2945+ ///
2946+ /// ```py
2947+ /// f(x)
2948+ /// ```
2949+ ///
2950+ /// As are reStructuredText literal blocks::
2951+ ///
2952+ /// f(x)
2953+ ///
2954+ ///
2955+ /// And reStructuredText code blocks:
2956+ ///
2957+ /// .. code-block:: python
2958+ ///
2959+ /// f(x)
2960+ /// """
2961+ /// pass
2962+ /// ```
2963+ ///
2964+ /// If a code snippt in a docstring contains invalid Python code or if the
2965+ /// formatter would otherwise write invalid Python code, then the code
2966+ /// example is ignored by the formatter and kept as-is.
2967+ ///
2968+ /// Currently, doctest, Markdown, reStructuredText literal blocks, and
2969+ /// reStructuredText code blocks are all supported and automatically
2970+ /// recognized. In the case of unlabeled fenced code blocks in Markdown and
2971+ /// reStructuredText literal blocks, the contents are assumed to be Python
2972+ /// and reformatted. As with any other format, if the contents aren't valid
2973+ /// Python, then the block is left untouched automatically.
2974+ #[ option(
2975+ default = "false" ,
2976+ value_type = "bool" ,
2977+ example = r#"
2978+ # Enable reformatting of code snippets in docstrings.
2979+ docstring-code-format = true
2980+ "#
2981+ ) ]
2982+ pub docstring_code_format : Option < bool > ,
2983+
2984+ /// Set the line length used when formatting code snippets in docstrings.
2985+ ///
2986+ /// This only has an effect when the `docstring-code-format` setting is
2987+ /// enabled.
2988+ ///
2989+ /// The default value for this setting is `"dynamic"`, which has the effect
2990+ /// of ensuring that any reformatted code examples in docstrings adhere to
2991+ /// the global line length configuration that is used for the surrounding
2992+ /// Python code. The point of this setting is that it takes the indentation
2993+ /// of the docstring into account when reformatting code examples.
2994+ ///
2995+ /// Alternatively, this can be set to a fixed integer, which will result
2996+ /// in the same line length limit being applied to all reformatted code
2997+ /// examples in docstrings. When set to a fixed integer, the indent of the
2998+ /// docstring is not taken into account. That is, this may result in lines
2999+ /// in the reformatted code example that exceed the globally configured
3000+ /// line length limit.
3001+ ///
3002+ /// For example, when this is set to `20` and `docstring-code-format` is
3003+ /// enabled, then this code:
3004+ ///
3005+ /// ```python
3006+ /// def f(x):
3007+ /// '''
3008+ /// Something about `f`. And an example:
3009+ ///
3010+ /// .. code-block:: python
3011+ ///
3012+ /// foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
3013+ /// '''
3014+ /// pass
3015+ /// ```
3016+ ///
3017+ /// ... will be reformatted (assuming the rest of the options are set
3018+ /// to their defaults) as:
3019+ ///
3020+ /// ```python
3021+ /// def f(x):
3022+ /// """
3023+ /// Something about `f`. And an example:
3024+ ///
3025+ /// .. code-block:: python
3026+ ///
3027+ /// (
3028+ /// foo,
3029+ /// bar,
3030+ /// quux,
3031+ /// ) = this_is_a_long_line(
3032+ /// lion,
3033+ /// hippo,
3034+ /// lemur,
3035+ /// bear,
3036+ /// )
3037+ /// """
3038+ /// pass
3039+ /// ```
3040+ #[ option(
3041+ default = r#""dynamic""# ,
3042+ value_type = r#"int | "dynamic""# ,
3043+ example = r#"
3044+ # Format all docstring code snippets with a line length of 60.
3045+ docstring-code-line-length = 60
3046+ "#
3047+ ) ]
3048+ pub docstring_code_line_length : Option < DocstringCodeLineWidth > ,
28993049}
29003050
29013051#[ cfg( test) ]
0 commit comments