Update snapshots to format module docstrings

crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.py

@@ -7,6 +7,22 @@
 # See: https://docs.python.org/3/library/doctest.html
 ###############################################################################
 
+"""
+This is a module docstring. with code in it. It should be formatted.
+.. code-block:: python
+
+    from bokeh.events import ButtonClick
+    from bokeh.models import Button, CustomJS
+
+    button = Button(                 )
+
+    button.js_on_event(ButtonClick, CustomJS(
+
+
+        code='console.log("JS:Click")'))
+"""
+
+
 # The simplest doctest to ensure basic formatting works.
 def doctest_simple():
     """

crates/ruff_python_formatter/resources/test/fixtures/ruff/quote_style.py

@@ -1,3 +1,4 @@
+# The next line is the docstring so it should be double quoted
 'single'
 "double"
 r'r single'

crates/ruff_python_formatter/src/statement/suite.rs

@@ -179,7 +179,7 @@ impl FormatRule<Suite, PyFormatContext<'_>> for FormatSuite {
                 true
             } else if is_module_docstring_newlines_enabled(f.context())
                 && self.kind == SuiteKind::TopLevel
-                && DocstringStmt::try_from_statement(first.statement(), self.kind).is_some()
+                && matches!(first, SuiteChildStatement::Docstring(_))
             {
                 // Only in preview mode, insert a newline after a module level docstring, but treat
                 // it as a docstring otherwise. See: https://github.com/psf/black/pull/3932.

crates/ruff_python_formatter/tests/snapshots/black_compatibility@cases__comments.py.snap

@@ -0,0 +1,324 @@
+---
+source: crates/ruff_python_formatter/tests/fixtures.rs
+input_file: crates/ruff_python_formatter/resources/test/fixtures/black/cases/comments.py
+---
+## Input
+
+```python
+#!/usr/bin/env python3
+# fmt: on
+# Some license here.
+#
+# Has many lines. Many, many lines.
+# Many, many, many lines.
+"""Module docstring.
+
+Possibly also many, many lines.
+"""
+
+import os.path
+import sys
+
+import a
+from b.c import X  # some noqa comment
+
+try:
+    import fast
+except ImportError:
+    import slow as fast
+
+
+# Some comment before a function.
+y = 1
+(
+    # some strings
+    y  # type: ignore
+)
+
+
+def function(default=None):
+    """Docstring comes first.
+
+    Possibly many lines.
+    """
+    # FIXME: Some comment about why this function is crap but still in production.
+    import inner_imports
+
+    if inner_imports.are_evil():
+        # Explains why we have this if.
+        # In great detail indeed.
+        x = X()
+        return x.method1()  # type: ignore
+
+    # This return is also commented for some reason.
+    return default
+
+
+# Explains why we use global state.
+GLOBAL_STATE = {"a": a(1), "b": a(2), "c": a(3)}
+
+
+# Another comment!
+# This time two lines.
+
+
+class Foo:
+    """Docstring for class Foo.  Example from Sphinx docs."""
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5  #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self):
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+
+#' <h1>This is pweave!</h1>
+
+
+@fast(really=True)
+async def wat():
+    # This comment, for some reason \
+    # contains a trailing backslash.
+    async with X.open_async() as x:  # Some more comments
+        result = await x.method1()
+    # Comment after ending a block.
+    if result:
+        print("A OK", file=sys.stdout)
+        # Comment between things.
+        print()
+
+
+# Some closing comments.
+# Maybe Vim or Emacs directives for formatting.
+# Who knows.
+```
+
+## Black Differences
+
+```diff
+--- Black
++++ Ruff
+@@ -6,8 +6,7 @@
+ # Many, many, many lines.
+ """Module docstring.
+ 
+-Possibly also many, many lines.
+-"""
++Possibly also many, many lines."""
+ 
+ import os.path
+ import sys
+```
+
+## Ruff Output
+
+```python
+#!/usr/bin/env python3
+# fmt: on
+# Some license here.
+#
+# Has many lines. Many, many lines.
+# Many, many, many lines.
+"""Module docstring.
+
+Possibly also many, many lines."""
+
+import os.path
+import sys
+
+import a
+from b.c import X  # some noqa comment
+
+try:
+    import fast
+except ImportError:
+    import slow as fast
+
+
+# Some comment before a function.
+y = 1
+(
+    # some strings
+    y  # type: ignore
+)
+
+
+def function(default=None):
+    """Docstring comes first.
+
+    Possibly many lines.
+    """
+    # FIXME: Some comment about why this function is crap but still in production.
+    import inner_imports
+
+    if inner_imports.are_evil():
+        # Explains why we have this if.
+        # In great detail indeed.
+        x = X()
+        return x.method1()  # type: ignore
+
+    # This return is also commented for some reason.
+    return default
+
+
+# Explains why we use global state.
+GLOBAL_STATE = {"a": a(1), "b": a(2), "c": a(3)}
+
+
+# Another comment!
+# This time two lines.
+
+
+class Foo:
+    """Docstring for class Foo.  Example from Sphinx docs."""
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5  #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self):
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+
+#' <h1>This is pweave!</h1>
+
+
+@fast(really=True)
+async def wat():
+    # This comment, for some reason \
+    # contains a trailing backslash.
+    async with X.open_async() as x:  # Some more comments
+        result = await x.method1()
+    # Comment after ending a block.
+    if result:
+        print("A OK", file=sys.stdout)
+        # Comment between things.
+        print()
+
+
+# Some closing comments.
+# Maybe Vim or Emacs directives for formatting.
+# Who knows.
+```
+
+## Black Output
+
+```python
+#!/usr/bin/env python3
+# fmt: on
+# Some license here.
+#
+# Has many lines. Many, many lines.
+# Many, many, many lines.
+"""Module docstring.
+
+Possibly also many, many lines.
+"""
+
+import os.path
+import sys
+
+import a
+from b.c import X  # some noqa comment
+
+try:
+    import fast
+except ImportError:
+    import slow as fast
+
+
+# Some comment before a function.
+y = 1
+(
+    # some strings
+    y  # type: ignore
+)
+
+
+def function(default=None):
+    """Docstring comes first.
+
+    Possibly many lines.
+    """
+    # FIXME: Some comment about why this function is crap but still in production.
+    import inner_imports
+
+    if inner_imports.are_evil():
+        # Explains why we have this if.
+        # In great detail indeed.
+        x = X()
+        return x.method1()  # type: ignore
+
+    # This return is also commented for some reason.
+    return default
+
+
+# Explains why we use global state.
+GLOBAL_STATE = {"a": a(1), "b": a(2), "c": a(3)}
+
+
+# Another comment!
+# This time two lines.
+
+
+class Foo:
+    """Docstring for class Foo.  Example from Sphinx docs."""
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5  #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self):
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+
+#' <h1>This is pweave!</h1>
+
+
+@fast(really=True)
+async def wat():
+    # This comment, for some reason \
+    # contains a trailing backslash.
+    async with X.open_async() as x:  # Some more comments
+        result = await x.method1()
+    # Comment after ending a block.
+    if result:
+        print("A OK", file=sys.stdout)
+        # Comment between things.
+        print()
+
+
+# Some closing comments.
+# Maybe Vim or Emacs directives for formatting.
+# Who knows.
+```
+
+