@@ -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
@@ -2948,6 +2948,156 @@ pub struct FormatOptions {
29482948 "#
29492949 ) ]
29502950 pub line_ending : Option < LineEnding > ,
2951+
2952+ /// Whether to format code snippets in docstrings.
2953+ ///
2954+ /// When this is enabled, Python code examples within docstrings are
2955+ /// automatically reformatted.
2956+ ///
2957+ /// For example, when this is enabled, the following code:
2958+ ///
2959+ /// ```python
2960+ /// def f(x):
2961+ /// """
2962+ /// Something about `f`. And an example in doctest format:
2963+ ///
2964+ /// >>> f( x )
2965+ ///
2966+ /// Markdown is also supported:
2967+ ///
2968+ /// ```py
2969+ /// f( x )
2970+ /// ```
2971+ ///
2972+ /// As are reStructuredText literal blocks::
2973+ ///
2974+ /// f( x )
2975+ ///
2976+ ///
2977+ /// And reStructuredText code blocks:
2978+ ///
2979+ /// .. code-block:: python
2980+ ///
2981+ /// f( x )
2982+ /// """
2983+ /// pass
2984+ /// ```
2985+ ///
2986+ /// ... will be reformatted (assuming the rest of the options are set to
2987+ /// their defaults) as:
2988+ ///
2989+ /// ```python
2990+ /// def f(x):
2991+ /// """
2992+ /// Something about `f`. And an example in doctest format:
2993+ ///
2994+ /// >>> f(x)
2995+ ///
2996+ /// Markdown is also supported:
2997+ ///
2998+ /// ```py
2999+ /// f(x)
3000+ /// ```
3001+ ///
3002+ /// As are reStructuredText literal blocks::
3003+ ///
3004+ /// f(x)
3005+ ///
3006+ ///
3007+ /// And reStructuredText code blocks:
3008+ ///
3009+ /// .. code-block:: python
3010+ ///
3011+ /// f(x)
3012+ /// """
3013+ /// pass
3014+ /// ```
3015+ ///
3016+ /// If a code snippt in a docstring contains invalid Python code or if the
3017+ /// formatter would otherwise write invalid Python code, then the code
3018+ /// example is ignored by the formatter and kept as-is.
3019+ ///
3020+ /// Currently, doctest, Markdown, reStructuredText literal blocks, and
3021+ /// reStructuredText code blocks are all supported and automatically
3022+ /// recognized. In the case of unlabeled fenced code blocks in Markdown and
3023+ /// reStructuredText literal blocks, the contents are assumed to be Python
3024+ /// and reformatted. As with any other format, if the contents aren't valid
3025+ /// Python, then the block is left untouched automatically.
3026+ #[ option(
3027+ default = "false" ,
3028+ value_type = "bool" ,
3029+ example = r#"
3030+ # Enable reformatting of code snippets in docstrings.
3031+ docstring-code-format = true
3032+ "#
3033+ ) ]
3034+ pub docstring_code_format : Option < bool > ,
3035+
3036+ /// Set the line length used when formatting code snippets in docstrings.
3037+ ///
3038+ /// This only has an effect when the `docstring-code-format` setting is
3039+ /// enabled.
3040+ ///
3041+ /// The default value for this setting is `"dynamic"`, which has the effect
3042+ /// of ensuring that any reformatted code examples in docstrings adhere to
3043+ /// the global line length configuration that is used for the surrounding
3044+ /// Python code. The point of this setting is that it takes the indentation
3045+ /// of the docstring into account when reformatting code examples.
3046+ ///
3047+ /// Alternatively, this can be set to a fixed integer, which will result
3048+ /// in the same line length limit being applied to all reformatted code
3049+ /// examples in docstrings. When set to a fixed integer, the indent of the
3050+ /// docstring is not taken into account. That is, this may result in lines
3051+ /// in the reformatted code example that exceed the globally configured
3052+ /// line length limit.
3053+ ///
3054+ /// For example, when this is set to `20` and `docstring-code-format` is
3055+ /// enabled, then this code:
3056+ ///
3057+ /// ```python
3058+ /// def f(x):
3059+ /// '''
3060+ /// Something about `f`. And an example:
3061+ ///
3062+ /// .. code-block:: python
3063+ ///
3064+ /// foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
3065+ /// '''
3066+ /// pass
3067+ /// ```
3068+ ///
3069+ /// ... will be reformatted (assuming the rest of the options are set
3070+ /// to their defaults) as:
3071+ ///
3072+ /// ```python
3073+ /// def f(x):
3074+ /// """
3075+ /// Something about `f`. And an example:
3076+ ///
3077+ /// .. code-block:: python
3078+ ///
3079+ /// (
3080+ /// foo,
3081+ /// bar,
3082+ /// quux,
3083+ /// ) = this_is_a_long_line(
3084+ /// lion,
3085+ /// hippo,
3086+ /// lemur,
3087+ /// bear,
3088+ /// )
3089+ /// """
3090+ /// pass
3091+ /// ```
3092+ #[ option(
3093+ default = r#""dynamic""# ,
3094+ value_type = r#"int | "dynamic""# ,
3095+ example = r#"
3096+ # Format all docstring code snippets with a line length of 60.
3097+ docstring-code-line-length = 60
3098+ "#
3099+ ) ]
3100+ pub docstring_code_line_length : Option < DocstringCodeLineWidth > ,
29513101}
29523102
29533103#[ cfg( test) ]
0 commit comments