]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

More minor documentation-related changes
authorŁukasz Langa <lukasz@langa.pl>
Thu, 29 Mar 2018 02:03:16 +0000 (19:03 -0700)
committerŁukasz Langa <lukasz@langa.pl>
Thu, 29 Mar 2018 02:03:16 +0000 (19:03 -0700)
black.py
docs/conf.py
docs/reference/reference_classes.rst

index a61a40fe5995e7a41fc0b29e6d3fa052f86f9ace..de861564a44bc7d05f89007e58ce687653c69dd8 100644 (file)
--- a/black.py
+++ b/black.py
@@ -38,7 +38,7 @@ err = partial(click.secho, fg='red', err=True)
 
 
 class NothingChanged(UserWarning):
 
 
 class NothingChanged(UserWarning):
-    """Raised by `format_file` when the reformatted code is the same as source."""
+    """Raised by `format_file()` when the reformatted code is the same as source."""
 
 
 class CannotSplit(Exception):
 
 
 class CannotSplit(Exception):
@@ -165,6 +165,13 @@ async def schedule_formatting(
     loop: BaseEventLoop,
     executor: Executor,
 ) -> int:
     loop: BaseEventLoop,
     executor: Executor,
 ) -> int:
+    """Run formatting of `sources` in parallel using the provided `executor`.
+
+    (Use ProcessPoolExecutors for actual parallelism.)
+
+    `line_length`, `write_back`, and `fast` options are passed to
+    :func:`format_file_in_place`.
+    """
     tasks = {
         src: loop.run_in_executor(
             executor, format_file_in_place, src, line_length, fast, write_back
     tasks = {
         src: loop.run_in_executor(
             executor, format_file_in_place, src, line_length, fast, write_back
@@ -193,7 +200,11 @@ async def schedule_formatting(
 def format_file_in_place(
     src: Path, line_length: int, fast: bool, write_back: bool = False
 ) -> bool:
 def format_file_in_place(
     src: Path, line_length: int, fast: bool, write_back: bool = False
 ) -> bool:
-    """Format the file and rewrite if changed. Return True if changed."""
+    """Format file under `src` path. Return True if changed.
+
+    If `write_back` is True, write reformatted code back to stdout.
+    `line_length` and `fast` options are passed to :func:`format_file_contents`.
+    """
     with tokenize.open(src) as src_buffer:
         src_contents = src_buffer.read()
     try:
     with tokenize.open(src) as src_buffer:
         src_contents = src_buffer.read()
     try:
@@ -212,7 +223,11 @@ def format_file_in_place(
 def format_stdin_to_stdout(
     line_length: int, fast: bool, write_back: bool = False
 ) -> bool:
 def format_stdin_to_stdout(
     line_length: int, fast: bool, write_back: bool = False
 ) -> bool:
-    """Format file on stdin and pipe output to stdout. Return True if changed."""
+    """Format file on stdin. Return True if changed.
+
+    If `write_back` is True, write reformatted code back to stdout.
+    `line_length` and `fast` arguments are passed to :func:`format_file_contents`.
+    """
     contents = sys.stdin.read()
     try:
         contents = format_file_contents(contents, line_length=line_length, fast=fast)
     contents = sys.stdin.read()
     try:
         contents = format_file_contents(contents, line_length=line_length, fast=fast)
@@ -229,7 +244,12 @@ def format_stdin_to_stdout(
 def format_file_contents(
     src_contents: str, line_length: int, fast: bool
 ) -> FileContent:
 def format_file_contents(
     src_contents: str, line_length: int, fast: bool
 ) -> FileContent:
-    """Reformats a file and returns its contents and encoding."""
+    """Reformats a file and returns its contents and encoding.
+
+    If `fast` is False, additionally confirm that the reformatted code is
+    valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
+    `line_length` is passed to :func:`format_str`.
+    """
     if src_contents.strip() == '':
         raise NothingChanged
 
     if src_contents.strip() == '':
         raise NothingChanged
 
@@ -244,7 +264,10 @@ def format_file_contents(
 
 
 def format_str(src_contents: str, line_length: int) -> FileContent:
 
 
 def format_str(src_contents: str, line_length: int) -> FileContent:
-    """Reformats a string and returns new contents."""
+    """Reformats a string and returns new contents.
+
+    `line_length` determines how many characters per line are allowed.
+    """
     src_node = lib2to3_parse(src_contents)
     dst_contents = ""
     lines = LineGenerator()
     src_node = lib2to3_parse(src_contents)
     dst_contents = ""
     lines = LineGenerator()
@@ -312,7 +335,7 @@ class Visitor(Generic[T]):
     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
 
     def visit(self, node: LN) -> Iterator[T]:
     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
 
     def visit(self, node: LN) -> Iterator[T]:
-        """Main method to start the visit process. Yields objects of type `T`.
+        """Main method to visit `node` and its children.
 
         It tries to find a `visit_*()` method for the given `node.type`, like
         `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
 
         It tries to find a `visit_*()` method for the given `node.type`, like
         `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
@@ -418,13 +441,9 @@ MATH_PRIORITY = 1
 class BracketTracker:
     """Keeps track of brackets on a line."""
 
 class BracketTracker:
     """Keeps track of brackets on a line."""
 
-    #: Current bracket depth.
     depth: int = 0
     depth: int = 0
-    #: All currently unclosed brackets.
     bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = Factory(dict)
     bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = Factory(dict)
-    #: All current delimiters with their assigned priority.
     delimiters: Dict[LeafID, Priority] = Factory(dict)
     delimiters: Dict[LeafID, Priority] = Factory(dict)
-    #: Last processed leaf, if any.
     previous: Optional[Leaf] = None
 
     def mark(self, leaf: Leaf) -> None:
     previous: Optional[Leaf] = None
 
     def mark(self, leaf: Leaf) -> None:
@@ -498,11 +517,8 @@ class BracketTracker:
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 
-    #: indentation level
     depth: int = 0
     depth: int = 0
-    #: list of leaves
     leaves: List[Leaf] = Factory(list)
     leaves: List[Leaf] = Factory(list)
-    #: inline comments that belong on this line
     comments: Dict[LeafID, Leaf] = Factory(dict)
     bracket_tracker: BracketTracker = Factory(BracketTracker)
     inside_brackets: bool = False
     comments: Dict[LeafID, Leaf] = Factory(dict)
     bracket_tracker: BracketTracker = Factory(BracketTracker)
     inside_brackets: bool = False
index 36b9a9843ddf74563bee07f38cb5569e1d8685d2..9599afd599b1a1d4488c63ef53dcac1bbfcadd95 100644 (file)
@@ -272,6 +272,8 @@ epub_exclude_files = ['search.html']
 
 # -- Extension configuration -------------------------------------------------
 
 
 # -- Extension configuration -------------------------------------------------
 
+autodoc_member_order = 'bysource'
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
index 380d39136c7c6ea9ff712b6fa6f1eb4d42996ca9..dc0805da39fe4b814e95c19c17e48346951d632d 100644 (file)
@@ -9,24 +9,26 @@
 -------------------------
 
 .. autoclass:: black.BracketTracker
 -------------------------
 
 .. autoclass:: black.BracketTracker
-   :members:
+    :members:
 
 :class:`EmptyLineTracker`
 -------------------------
 
 .. autoclass:: black.EmptyLineTracker
 
 :class:`EmptyLineTracker`
 -------------------------
 
 .. autoclass:: black.EmptyLineTracker
-   :members:
+    :members:
 
 :class:`Line`
 -------------
 
 .. autoclass:: black.Line
     :members:
 
 :class:`Line`
 -------------
 
 .. autoclass:: black.Line
     :members:
+    :special-members: __str__, __bool__
 
 
-:class:`LineGenerator` (:class:`Visitor` [:class:`Line`])
--------------------------------------------------------
+:class:`LineGenerator`
+----------------------
 
 .. autoclass:: black.LineGenerator
 
 .. autoclass:: black.LineGenerator
+    :show-inheritance:
     :members:
 
 :class:`Report`
     :members:
 
 :class:`Report`
 
 .. autoclass:: black.Report
     :members:
 
 .. autoclass:: black.Report
     :members:
+    :special-members: __str__
 
 
-:class:`UnformattedLines` (:class:`Line`)
-----------------------------------------
+:class:`UnformattedLines`
+-------------------------
 
 .. autoclass:: black.UnformattedLines
 
 .. autoclass:: black.UnformattedLines
+    :show-inheritance:
     :members:
 
     :members:
 
-:class:`Visitor` (Generic[T])
-----------------------------
+:class:`Visitor`
+----------------
 
 .. autoclass:: black.Visitor
 
 .. autoclass:: black.Visitor
+    :show-inheritance:
     :members:
     :members: