More minor documentation-related changes

diff --git a/black.py b/black.py
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

diff --git a/docs/conf.py b/docs/conf.py
index 36b9a9843ddf74563bee07f38cb5569e1d8685d2..9599afd599b1a1d4488c63ef53dcac1bbfcadd95 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -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.

diff --git a/docs/reference/reference_classes.rst b/docs/reference/reference_classes.rst
index 380d39136c7c6ea9ff712b6fa6f1eb4d42996ca9..dc0805da39fe4b814e95c19c17e48346951d632d 100644 (file)
--- a/docs/reference/reference_classes.rst
+++ b/docs/reference/reference_classes.rst
@@ -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`


@@ -34,15 +36,18 @@
 
 .. 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: