@alloy-js/python 0.4.0-dev.2 → 0.4.0-dev.5

package/dist/dev/test/pydocs.test.js

@@ -0,0 +1,1675 @@
+import { createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import { Prose } from "@alloy-js/core";
+import { d } from "@alloy-js/core/testing";
+import { describe, expect, it } from "vitest";
+import { enumModule } from "../src/builtins/python.js";
+import * as py from "../src/index.js";
+import { assertFileContents, toSourceText, toSourceTextMultiple } from "./utils.js";
+describe("PyDoc", () => {
+  it("formats properly", () => {
+    const res = toSourceText([_$createComponent(py.PyDoc, {
+      get children() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a long docstring that will be broken in lines. We will also render another paragraph after this one."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 17,
+          columnNumber: 11
+        }), _$createComponent(Prose, {
+          children: "This is another paragraph, and there's a line break before it."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 21,
+          columnNumber: 11
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 16,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 40
+      }
+    });
+    expect(res).toRenderTo(d`
+        """
+        This is an example of a long docstring
+        that will be broken in lines. We will
+        also render another paragraph after this
+        one.
+        
+        This is another paragraph, and there's a
+        line break before it.
+        """
+
+        
+      `);
+  });
+});
+describe("PyDocExample", () => {
+  it("creates docstring with a code sample", () => {
+    const res = toSourceText([_$createComponent(py.PyDoc, {
+      get children() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a docstring with a code sample."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 52,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: "print(\"Hello world!\")"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 53,
+          columnNumber: 11
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 51,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 40
+      }
+    });
+    expect(res).toRenderTo(d`
+      """
+      This is an example of a docstring with a
+      code sample.
+      
+      >> print("Hello world!")
+      """
+
+
+      `);
+  });
+  it("creates docstring with more than one code sample", () => {
+    const res = toSourceText([_$createComponent(py.PyDoc, {
+      get children() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a docstring with a code sample."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 77,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: "print(\"Hello world!\")"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 78,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: "print(\"Hello world again!\")"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 79,
+          columnNumber: 11
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 76,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 40
+      }
+    });
+    expect(res).toRenderTo(d`
+      """
+      This is an example of a docstring with a
+      code sample.
+      
+      >> print("Hello world!")
+      
+      >> print("Hello world again!")
+      """
+
+
+      `);
+  });
+  it("creates docstring with a multiline code sample", () => {
+    const res = toSourceText([_$createComponent(py.PyDoc, {
+      get children() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a docstring with a code sample."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 105,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: `print("Hello world!")\nx = "Hello"\nprint(x)`
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 106,
+          columnNumber: 11
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 104,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 40
+      }
+    });
+    expect(res).toRenderTo(d`
+      """
+      This is an example of a docstring with a
+      code sample.
+      
+      >> print("Hello world!")
+      >> x = "Hello"
+      >> print(x)
+      """
+
+
+      `);
+  });
+});
+describe("SimpleCommentBlock", () => {
+  it("renders simple comment block", () => {
+    const res = toSourceText([_$createComponent(py.SimpleCommentBlock, {
+      children: "This is a simple comment block that spans multiple lines and should be split automatically."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 134,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+          # This is a simple comment block that spans multiple lines and should be split
+          # automatically.
+          
+          `);
+  });
+  it("renders comment block with line breaks", () => {
+    const res = toSourceText([_$createComponent(py.SimpleCommentBlock, {
+      children: "First line of comment.\\nSecond line of comment."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 150,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+          # First line of comment.
+          # Second line of comment.
+          
+          `);
+  });
+});
+describe("SimpleInlineComment", () => {
+  it("renders inline comment", () => {
+    const res = toSourceText([["x = 42", _$createComponent(py.SimpleInlineComment, {
+      children: "This is an inline comment"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 169,
+      columnNumber: 9
+    })]]);
+    expect(res).toRenderTo(d`
+          x = 42  # This is an inline comment
+          `);
+  });
+  it("renders inline comment with complex text", () => {
+    const res = toSourceText([["result = calculate()", _$createComponent(py.SimpleInlineComment, {
+      children: "TODO: Add error handling here"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 185,
+      columnNumber: 9
+    })]]);
+    expect(res).toRenderTo(d`
+          result = calculate()  # TODO: Add error handling here
+          `);
+  });
+});
+describe("New Documentation Components", () => {
+  it("ModuleDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This module demonstrates documentation as specified by the Google Python Style Guide."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 203,
+          columnNumber: 11
+        })];
+      },
+      attributes: [{
+        name: "module_level_variable1",
+        type: "int",
+        children: "Module level variables may be documented."
+      }],
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(\"mod\")"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 215,
+          columnNumber: 20
+        })];
+      },
+      seeAlso: ["another_module.func", "RelatedClass"],
+      warning: "Internal API.",
+      deprecated: "Use new_module instead.",
+      todo: ["For module TODOs", "You have to also use sphinx.ext.todo extension"]
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 201,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        This module demonstrates documentation as specified by the Google Python Style
+        Guide.
+
+        Attributes:
+            module_level_variable1 (int): Module level variables may be documented.
+
+        Examples:
+            >> print("mod")
+
+        See Also:
+            another_module.func
+            RelatedClass
+
+        Warning:
+            Internal API.
+
+        Deprecated:
+            Use new_module instead.
+
+        Todo:
+            * For module TODOs
+            * You have to also use sphinx.ext.todo extension
+        """
+
+
+        `);
+  });
+  it("PropertyDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Properties should be documented in their getter method."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 262,
+          columnNumber: 11
+        })];
+      },
+      returns: "str: The readonly property value.",
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(obj.name)"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 267,
+          columnNumber: 20
+        })];
+      },
+      seeAlso: ["other_property"],
+      warning: "Access may be slow.",
+      deprecated: "Use full_name instead.",
+      note: "If the setter method contains notable behavior, it should be mentioned here."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 260,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Properties should be documented in their getter method.
+
+        Returns:
+            str: The readonly property value.
+
+        Examples:
+            >> print(obj.name)
+
+        See Also:
+            other_property
+
+        Warning:
+            Access may be slow.
+
+        Deprecated:
+            Use full_name instead.
+
+        Note:
+            If the setter method contains notable behavior, it should be mentioned here.
+        """
+
+
+        `);
+  });
+  it("GeneratorDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Generators have a Yields section instead of a Returns section."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 308,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "The upper limit of the range to generate, from 0 to n - 1."
+      }],
+      yields: "int: The next number in the range of 0 to n - 1.",
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(next(gen))"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 320,
+          columnNumber: 20
+        })];
+      },
+      seeAlso: ["make_generator"],
+      warning: "Do not consume in tight loops without sleep.",
+      deprecated: "Use new_generator instead.",
+      note: "Examples should be written in doctest format."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 306,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Generators have a Yields section instead of a Returns section.
+
+        Args:
+            n (int): The upper limit of the range to generate, from 0 to n - 1.
+
+        Yields:
+            int: The next number in the range of 0 to n - 1.
+
+        Examples:
+            >> print(next(gen))
+
+        See Also:
+            make_generator
+
+        Warning:
+            Do not consume in tight loops without sleep.
+
+        Deprecated:
+            Use new_generator instead.
+
+        Note:
+            Examples should be written in doctest format.
+        """
+
+
+        `);
+  });
+  it("ExceptionDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Exceptions are documented in the same way as classes."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 364,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "msg",
+        type: "str",
+        doc: "Human readable string describing the exception."
+      }, {
+        name: "code",
+        type: "int",
+        default: undefined,
+        doc: "Error code."
+      }],
+      attributes: [{
+        name: "msg",
+        type: "str",
+        children: "Human readable string describing the exception."
+      }, {
+        name: "code",
+        type: "int",
+        children: "Exception error code."
+      }],
+      seeAlso: ["BaseException"],
+      deprecated: "Use NewException instead.",
+      note: "Do not include the 'self' parameter in the Args section."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 362,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Exceptions are documented in the same way as classes.
+
+        Args:
+            msg (str): Human readable string describing the exception.
+
+            code (int): Error code.
+
+        Attributes:
+            msg (str): Human readable string describing the exception.
+
+            code (int): Exception error code.
+
+        See Also:
+            BaseException
+
+        Deprecated:
+            Use NewException instead.
+
+        Note:
+            Do not include the 'self' parameter in the Args section.
+        """
+
+
+        `);
+  });
+  it("MethodDoc renders correctly without default note", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Class methods are similar to regular functions."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 431,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "param1",
+        doc: "The first parameter."
+      }, {
+        name: "param2",
+        doc: "The second parameter."
+      }],
+      returns: "True if successful, False otherwise.",
+      overrides: "Base.method"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 429,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Class methods are similar to regular functions.
+
+        Args:
+            param1: The first parameter.
+
+            param2: The second parameter.
+
+        Returns:
+            True if successful, False otherwise.
+
+        Overrides:
+            Base.method
+        """
+
+
+        `);
+  });
+  it("MethodDoc renders correctly with custom note", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Class methods are similar to regular functions."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 474,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "param1",
+        doc: "The first parameter."
+      }],
+      returns: "True if successful, False otherwise.",
+      note: "This method has special behavior when called multiple times."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 472,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Class methods are similar to regular functions.
+
+        Args:
+            param1: The first parameter.
+
+        Returns:
+            True if successful, False otherwise.
+
+        Note:
+            This method has special behavior when called multiple times.
+        """
+
+
+        `);
+  });
+  it("ModuleDoc with minimal content", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Simple module description."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 510,
+          columnNumber: 23
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 509,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Simple module description.
+        """
+
+
+        `);
+  });
+  it("ModuleDoc with only todo items", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Module with pending tasks."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 528,
+          columnNumber: 23
+        })];
+      },
+      todo: ["Implement feature X", "Add more tests", "Update documentation"]
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 527,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Module with pending tasks.
+
+        Todo:
+            * Implement feature X
+            * Add more tests
+            * Update documentation
+        """
+
+
+        `);
+  });
+  it("PropertyDoc minimal (description only)", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A simple readonly property."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 552,
+          columnNumber: 23
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 551,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A simple readonly property.
+        """
+
+
+        `);
+  });
+  it("PropertyDoc with getter and setter info", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Properties with both a getter and setter should only be documented in their getter method."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 571,
+          columnNumber: 11
+        })];
+      },
+      returns: ":obj:`list` of :obj:`str`: The property value.",
+      note: "If the setter method contains notable behavior, it should be mentioned here."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 569,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Properties with both a getter and setter should only be documented in their
+        getter method.
+
+        Returns:
+            :obj:\`list\` of :obj:\`str\`: The property value.
+
+        Note:
+            If the setter method contains notable behavior, it should be mentioned here.
+        """
+
+
+        `);
+  });
+  it("GeneratorDoc with complex parameters", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A more complex generator example with multiple parameters."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 603,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "start",
+        type: "int",
+        default: "0",
+        doc: "Starting value for the sequence."
+      }, {
+        name: "stop",
+        type: "int",
+        doc: "Ending value for the sequence (exclusive)."
+      }, {
+        name: "step",
+        type: "int",
+        default: "1",
+        doc: "Step size between values."
+      }],
+      yields: "int: The next number in the sequence.",
+      raises: ["ValueError: If step is zero.", "TypeError: If parameters are not integers."]
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 601,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A more complex generator example with multiple parameters.
+
+        Args:
+            start (int, optional): Starting value for the sequence. Defaults to "0".
+
+            stop (int): Ending value for the sequence (exclusive).
+
+            step (int, optional): Step size between values. Defaults to "1".
+
+        Yields:
+            int: The next number in the sequence.
+
+        Raises:
+            ValueError: If step is zero.
+
+        Raises:
+            TypeError: If parameters are not integers.
+        """
+
+
+        `);
+  });
+  it("ExceptionDoc with comprehensive documentation", () => {
+    const res = toSourceText([_$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A custom exception for authentication failures."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 665,
+          columnNumber: 11
+        }), _$createComponent(Prose, {
+          children: "This exception is raised when authentication credentials are invalid or when authentication tokens have expired."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 666,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "message",
+        type: "str",
+        doc: "Human readable error message describing the authentication failure."
+      }, {
+        name: "error_code",
+        type: "int",
+        default: "401",
+        doc: "HTTP error code associated with the authentication failure."
+      }, {
+        name: "retry_after",
+        type: "int",
+        default: undefined,
+        doc: "Number of seconds to wait before retrying authentication."
+      }],
+      attributes: [{
+        name: "message",
+        type: "str",
+        children: "The error message."
+      }, {
+        name: "error_code",
+        type: "int",
+        children: "HTTP status code."
+      }, {
+        name: "retry_after",
+        type: "int",
+        children: "Retry delay in seconds, if applicable."
+      }],
+      note: "This exception should be caught and handled gracefully in production code."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 663,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A custom exception for authentication failures.
+
+        This exception is raised when authentication credentials are invalid or when
+        authentication tokens have expired.
+
+        Args:
+            message (str): Human readable error message describing the authentication
+                failure.
+
+            error_code (int, optional): HTTP error code associated with the
+                authentication failure. Defaults to "401".
+
+            retry_after (int): Number of seconds to wait before retrying authentication.
+
+        Attributes:
+            message (str): The error message.
+
+            error_code (int): HTTP status code.
+
+            retry_after (int): Retry delay in seconds, if applicable.
+
+        Note:
+            This exception should be caught and handled gracefully in production code.
+        """
+
+
+        `);
+  });
+  it("MethodDoc with raises but no returns", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A method that performs an action but doesn't return a value."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 748,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "data",
+        type: "bytes",
+        doc: "Raw data to process."
+      }],
+      raises: ["ValueError: If data is empty or invalid.", "IOError: If processing fails due to I/O issues."]
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 746,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A method that performs an action but doesn't return a value.
+
+        Args:
+            data (bytes): Raw data to process.
+
+        Raises:
+            ValueError: If data is empty or invalid.
+
+        Raises:
+            IOError: If processing fails due to I/O issues.
+        """
+
+
+        `);
+  });
+  it("MethodDoc with no parameters", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A simple method with no parameters (except self)."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 790,
+          columnNumber: 11
+        })];
+      },
+      returns: "bool: True if the operation was successful.",
+      note: "This is a parameterless method that only operates on instance state."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 788,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A simple method with no parameters (except self).
+
+        Returns:
+            bool: True if the operation was successful.
+
+        Note:
+            This is a parameterless method that only operates on instance state.
+        """
+
+
+        `);
+  });
+  it("AttributeDoc standalone usage", () => {
+    const res = toSourceText([_$createComponent(py.PyDoc, {
+      get children() {
+        return _$createComponent(py.AttributeDoc, {
+          name: "connection_timeout",
+          type: "float",
+          children: "Maximum time in seconds to wait for a connection to be established."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 817,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 816,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        connection_timeout (float): Maximum time in seconds to wait for a connection to
+            be established.
+        """
+
+
+        `);
+  });
+  it("GeneratorDoc with examples in description", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Generators have a Yields section instead of a Returns section."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 839,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: `print([i for i in example_generator(4)])\n[0, 1, 2, 3]`
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 842,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "The upper limit of the range to generate, from 0 to n - 1."
+      }],
+      yields: "int: The next number in the range of 0 to n - 1.",
+      note: "Examples should be written in doctest format, and should illustrate how to use the function."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 837,
+      columnNumber: 7
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Generators have a Yields section instead of a Returns section.
+
+        >> print([i for i in example_generator(4)])
+        >> [0, 1, 2, 3]
+
+        Args:
+            n (int): The upper limit of the range to generate, from 0 to n - 1.
+
+        Yields:
+            int: The next number in the range of 0 to n - 1.
+
+        Note:
+            Examples should be written in doctest format, and should illustrate how to use the function.
+        """
+
+
+        `);
+  });
+});
+describe("Full example", () => {
+  it("renders correctly in a Class", () => {
+    const doc = _$createComponent(py.ClassDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a long docstring that will be broken in lines. We will also render another paragraph after this one."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 887,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: `print("Hello world!")\nx = "Hello"\nprint(x)`
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 891,
+          columnNumber: 11
+        })];
+      },
+      attributes: [{
+        name: "attr1",
+        type: "str",
+        children: "Description of attr1."
+      }, {
+        name: "attr2",
+        type: "int",
+        children: "Description of attr2."
+      }],
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(\"class-doc\")"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 907,
+          columnNumber: 20
+        })];
+      },
+      seeAlso: ["RelatedClass", "helper_function"],
+      warning: "This class is experimental.",
+      deprecated: "Use NewClass instead.",
+      parameters: [{
+        name: "somebody",
+        type: "str",
+        default: "John Doe",
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
+      }, {
+        name: "somebody2",
+        type: "str",
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
+      }],
+      note: "Do not include the 'self' parameter in the Args section.",
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 885,
+      columnNumber: 7
+    });
+    const res = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "A",
+      doc: doc,
+      get children() {
+        return _$createComponent(py.StatementList, {
+          get children() {
+            return [_$createComponent(py.VariableDeclaration, {
+              name: "just_name"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 932,
+              columnNumber: 13
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "name_and_type",
+              type: "int"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 933,
+              columnNumber: 13
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "name_type_and_value",
+              type: "int",
+              initializer: 12
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 934,
+              columnNumber: 13
+            })];
+          }
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 931,
+          columnNumber: 11
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 930,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 80,
+        tabWidth: 4
+      }
+    });
+    expect(res).toRenderTo(d`
+          class A:
+              """
+              This is an example of a long docstring that will be broken in lines. We will
+              also render another paragraph after this one.
+
+              >> print("Hello world!")
+              >> x = "Hello"
+              >> print(x)
+
+              Attributes:
+                  attr1 (str): Description of attr1.
+
+                  attr2 (int): Description of attr2.
+
+              Args:
+                  somebody (str, optional): Somebody's name. This can be any string
+                      representing a person, whether it's a first name, full name,
+                      nickname, or even a codename (e.g., 'Agent X'). It's used primarily
+                      for display purposes, logging, or greeting messages and is not
+                      required to be unique or validated unless specified by the caller.
+                      Defaults to \"John Doe\".
+
+                  somebody2 (str): Somebody's name. This can be any string representing a
+                      person, whether it's a first name, full name, nickname, or even a
+                      codename (e.g., 'Agent X'). It's used primarily for display
+                      purposes, logging, or greeting messages and is not required to be
+                      unique or validated unless specified by the caller.
+
+              Examples:
+                  >> print("class-doc")
+
+              See Also:
+                  RelatedClass
+                  helper_function
+
+              Warning:
+                  This class is experimental.
+
+              Deprecated:
+                  Use NewClass instead.
+
+              Note:
+                  Do not include the 'self' parameter in the Args section.
+              """
+
+              just_name = None
+              name_and_type: int = None
+              name_type_and_value: int = 12
+
+
+          `);
+  });
+  it("renders correctly in a Function", () => {
+    const doc = _$createComponent(py.FunctionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This is an example of a long docstring that will be broken in lines. We will also render another paragraph after this one."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1005,
+          columnNumber: 11
+        }), _$createComponent(py.PyDocExample, {
+          children: `print("Hello world!")\nx = "Hello"\nprint(x)`
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1009,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "somebody",
+        type: "str",
+        default: "John Doe",
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
+      }, {
+        name: "somebody2",
+        type: "str",
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
+      }],
+      returns: "The return value. True for success, False otherwise.",
+      yields: "int: The next number in the sequence.",
+      raises: ["ValueError: If somebody2 is equal to somebody."],
+      note: "This function can be used as both a regular function and a generator.",
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1003,
+      columnNumber: 7
+    });
+    const res = toSourceText([_$createComponent(py.FunctionDeclaration, {
+      name: "some_function",
+      doc: doc,
+      get children() {
+        return _$createComponent(py.StatementList, {
+          get children() {
+            return [_$createComponent(py.VariableDeclaration, {
+              name: "just_name"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 1037,
+              columnNumber: 13
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "name_and_type",
+              type: "number"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 1038,
+              columnNumber: 13
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "name_type_and_value",
+              type: "number",
+              initializer: 12
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 1039,
+              columnNumber: 13
+            })];
+          }
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1036,
+          columnNumber: 11
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1035,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 80,
+        tabWidth: 4
+      }
+    });
+    expect(res).toRenderTo(d`
+          def some_function():
+              """
+              This is an example of a long docstring that will be broken in lines. We will
+              also render another paragraph after this one.
+
+              >> print("Hello world!")
+              >> x = "Hello"
+              >> print(x)
+
+              Args:
+                  somebody (str, optional): Somebody's name. This can be any string
+                      representing a person, whether it's a first name, full name,
+                      nickname, or even a codename (e.g., 'Agent X'). It's used primarily
+                      for display purposes, logging, or greeting messages and is not
+                      required to be unique or validated unless specified by the caller.
+                      Defaults to \"John Doe\".
+
+                  somebody2 (str): Somebody's name. This can be any string representing a
+                      person, whether it's a first name, full name, nickname, or even a
+                      codename (e.g., 'Agent X'). It's used primarily for display
+                      purposes, logging, or greeting messages and is not required to be
+                      unique or validated unless specified by the caller.
+
+              Returns:
+                  The return value. True for success, False otherwise.
+
+              Yields:
+                  int: The next number in the sequence.
+
+              Raises:
+                  ValueError: If somebody2 is equal to somebody.
+
+              Note:
+                  This function can be used as both a regular function and a generator.
+              """
+              just_name = None
+              name_and_type: number = None
+              name_type_and_value: number = 12
+
+
+          `);
+  });
+  it("renders correctly in a Variable", () => {
+    const res = toSourceText([_$createComponent(py.VariableDeclaration, {
+      name: "myVar",
+      initializer: 42,
+      doc: "This is a very long docstring that will be broken in two lines when rendered. This part of the docstring will be in the second line."
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1099,
+      columnNumber: 9
+    })], {
+      printOptions: {
+        printWidth: 80,
+        tabWidth: 4
+      }
+    });
+    expect(res).toRenderTo(d`
+            # This is a very long docstring that will be broken in two lines when rendered.
+            # This part of the docstring will be in the second line.
+            my_var = 42
+            `);
+  });
+  it("classic enum with explicit values", () => {
+    const doc = _$createComponent(py.ClassDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "An enum representing colors."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1120,
+          columnNumber: 23
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1119,
+      columnNumber: 7
+    });
+    const result = toSourceText([_$createComponent(py.ClassEnumDeclaration, {
+      name: "Color",
+      baseType: "IntEnum",
+      members: [{
+        name: "RED",
+        value: "1",
+        doc: "The color red."
+      }, {
+        name: "GREEN",
+        value: "2",
+        doc: "The color green."
+      }, {
+        name: "BLUE",
+        value: "3",
+        doc: "The color blue."
+      }],
+      doc: doc
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1125,
+      columnNumber: 9
+    })], {
+      externals: [enumModule]
+    });
+    const expected = d`
+      from enum import IntEnum
+
+
+      class Color(IntEnum):
+          """
+          An enum representing colors.
+          """
+
+          RED = 1
+          """
+          The color red.
+          """
+          GREEN = 2
+          """
+          The color green.
+          """
+          BLUE = 3
+          """
+          The color blue.
+          """
+
+
+    `;
+    expect(result).toRenderTo(expected);
+  });
+  it("ModuleDoc with SourceFile integration", () => {
+    const moduleDoc = _$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This module provides utility functions for data processing. It includes functions for validation, transformation, and analysis."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1169,
+          columnNumber: 11
+        })];
+      },
+      attributes: [{
+        name: "DEFAULT_TIMEOUT",
+        type: "int",
+        children: "Default timeout value in seconds."
+      }, {
+        name: "MAX_RETRIES",
+        type: "int",
+        children: "Maximum number of retry attempts."
+      }],
+      todo: ["Add caching functionality", "Improve error messages"],
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1167,
+      columnNumber: 7
+    });
+    const content = _$createComponent(py.SourceFile, {
+      path: "utils.py",
+      doc: moduleDoc,
+      get children() {
+        return [_$createComponent(py.VariableDeclaration, {
+          name: "DEFAULT_TIMEOUT",
+          initializer: 30
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1193,
+          columnNumber: 9
+        }), _$createComponent(py.VariableDeclaration, {
+          name: "MAX_RETRIES",
+          initializer: 3
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1194,
+          columnNumber: 9
+        }), _$createComponent(py.FunctionDeclaration, {
+          name: "process_data",
+          children: "pass"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1195,
+          columnNumber: 9
+        })];
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1192,
+      columnNumber: 7
+    });
+    const res = toSourceTextMultiple([content]);
+    const file = res.contents.find(f => f.kind === "file" && f.path === "utils.py");
+    expect(file).toBeDefined();
+    assertFileContents(res, {
+      "utils.py": d`
+        """
+        This module provides utility functions for data processing. It includes
+        functions for validation, transformation, and analysis.
+
+        Attributes:
+            DEFAULT_TIMEOUT (int): Default timeout value in seconds.
+
+            MAX_RETRIES (int): Maximum number of retry attempts.
+
+        Todo:
+            * Add caching functionality
+            * Improve error messages
+        """
+
+        default_timeout = 30
+
+        max_retries = 3
+
+        def process_data():
+            pass
+
+
+        `
+    });
+  });
+  it("GeneratorDoc with FunctionDeclaration integration", () => {
+    const generatorDoc = _$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A generator function that yields fibonacci numbers. This is an efficient way to generate the sequence on demand."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1239,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "Number of fibonacci numbers to generate."
+      }],
+      yields: "int: The next fibonacci number in the sequence.",
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1237,
+      columnNumber: 7
+    });
+    const result = toSourceText([_$createComponent(py.FunctionDeclaration, {
+      name: "fibonacci_generator",
+      doc: generatorDoc,
+      children: "yield 0"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1257,
+      columnNumber: 7
+    })]);
+    expect(result).toRenderTo(d`
+        def fibonacci_generator():
+            """
+            A generator function that yields fibonacci numbers. This is an efficient way
+            to generate the sequence on demand.
+
+            Args:
+                n (int): Number of fibonacci numbers to generate.
+
+            Yields:
+                int: The next fibonacci number in the sequence.
+            """
+            yield 0
+
+
+        `);
+  });
+  it("ExceptionDoc with ClassDeclaration integration", () => {
+    const exceptionDoc = _$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Custom exception raised when data validation fails. This exception includes details about the validation error."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1286,
+          columnNumber: 11
+        })];
+      },
+      attributes: [{
+        name: "field_name",
+        type: "str",
+        children: "Name of the field that failed validation."
+      }, {
+        name: "error_code",
+        type: "int",
+        children: "Numeric error code for the validation failure."
+      }],
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1284,
+      columnNumber: 7
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "ValidationError",
+      bases: ["Exception"],
+      doc: exceptionDoc,
+      get children() {
+        return _$createComponent(py.StatementList, {
+          get children() {
+            return [_$createComponent(py.VariableDeclaration, {
+              name: "field_name",
+              type: "str"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 1314,
+              columnNumber: 11
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "error_code",
+              type: "int"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 1315,
+              columnNumber: 11
+            })];
+          }
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1313,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1308,
+      columnNumber: 7
+    })]);
+    expect(result).toRenderTo(d`
+        class ValidationError(Exception):
+            """
+            Custom exception raised when data validation fails. This exception includes
+            details about the validation error.
+
+            Attributes:
+                field_name (str): Name of the field that failed validation.
+
+                error_code (int): Numeric error code for the validation failure.
+            """
+
+            field_name: str = None
+            error_code: int = None
+
+
+        `);
+  });
+  it("PropertyDoc with FunctionDeclaration (as property method) integration", () => {
+    const propertyDoc = _$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "The full name of the person, combining first and last name. This property automatically formats the name with proper capitalization."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1345,
+          columnNumber: 11
+        })];
+      },
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1343,
+      columnNumber: 7
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "Person",
+      get children() {
+        return _$createComponent(py.PropertyDeclaration, {
+          name: "full_name",
+          doc: propertyDoc,
+          type: "str",
+          children: "return \"John Doe\""
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1356,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1355,
+      columnNumber: 7
+    })]);
+    expect(result).toRenderTo(`
+      class Person:
+          @property
+          def full_name(self) -> str:
+              """
+              The full name of the person, combining first and last name. This
+              property automatically formats the name with proper capitalization.
+              """
+              return "John Doe"
+      
+      
+    `);
+  });
+  it("MethodDoc with FunctionDeclaration (inside class) integration", () => {
+    const methodDoc = _$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Validates the input data according to the defined schema. This method performs comprehensive validation including type checking."
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1380,
+          columnNumber: 11
+        })];
+      },
+      parameters: [{
+        name: "data",
+        type: "dict",
+        doc: "The data dictionary to validate."
+      }, {
+        name: "strict",
+        type: "bool",
+        default: "True",
+        doc: "Whether to enforce strict validation rules."
+      }],
+      returns: "bool: True if validation passes, False otherwise.",
+      raises: ["ValidationError: If data format is invalid."],
+      note: "This method modifies the internal validation state.",
+      style: "google"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1378,
+      columnNumber: 7
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "DataValidator",
+      get children() {
+        return _$createComponent(py.MethodDeclaration, {
+          name: "validate",
+          doc: methodDoc,
+          parameters: [{
+            name: "data",
+            type: "dict"
+          }, {
+            name: "strict",
+            type: "bool",
+            default: true
+          }],
+          returnType: "bool",
+          children: "return self.validate(data, strict)"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 1407,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 1406,
+      columnNumber: 7
+    })]);
+    expect(result).toRenderTo(d`
+        class DataValidator:
+            def validate(self, data: dict, strict: bool = True) -> bool:
+                """
+                Validates the input data according to the defined schema. This method
+                performs comprehensive validation including type checking.
+
+                Args:
+                    data (dict): The data dictionary to validate.
+
+                    strict (bool, optional): Whether to enforce strict validation rules.
+                        Defaults to "True".
+
+                Returns:
+                    bool: True if validation passes, False otherwise.
+
+                Raises:
+                    ValidationError: If data format is invalid.
+
+                Note:
+                    This method modifies the internal validation state.
+                """
+                return self.validate(data, strict)
+
+
+
+        `);
+  });
+});
+//# sourceMappingURL=pydocs.test.js.map