Fix documentation build

diff --git a/black.py b/black.py
index d25756365d574c28f06f5034fb99858bd086f39f..f2c450c33876a615472e5d28ec641cc1a4ccfb83 100644 (file)
--- a/black.py
+++ b/black.py
@@ -2013,6 +2013,16 @@ def generate_comments(leaf: LN) -> Iterator[Leaf]:
 
 @dataclass
 class ProtoComment:
+    """Describes a piece of syntax that is a comment.
+
+    It's not a :class:`blib2to3.pytree.Leaf` so that:
+
+    * it can be cached (`Leaf` objects should not be reused more than once as
+      they store their lineno, column, prefix, and parent information);
+    * `newlines` and `consumed` fields are kept separate from the `value`. This
+      simplifies handling of special marker comments like ``# fmt: off/on``.
+    """
+
     type: int  # token.COMMENT or STANDALONE_COMMENT
     value: str  # content of the comment
     newlines: int  # how many newlines before the comment
@@ -2021,6 +2031,7 @@ class ProtoComment:
 
 @lru_cache(maxsize=4096)
 def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
+    """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
     result: List[ProtoComment] = []
     if not prefix or "#" not in prefix:
         return result

diff --git a/docs/reference/reference_classes.rst b/docs/reference/reference_classes.rst
index d99057e34293461a7e05274c6a522272055dc0f3..3af0b47893b11940ed98e41902527ebb8a9b04fc 100644 (file)
--- a/docs/reference/reference_classes.rst
+++ b/docs/reference/reference_classes.rst
@@ -6,7 +6,7 @@
 .. currentmodule:: black
 
 :class:`BracketTracker`
--------------------------
+-----------------------
 
 .. autoclass:: black.BracketTracker
     :members:
@@ -31,6 +31,12 @@
     :show-inheritance:
     :members:
 
+:class:`ProtoComment`
+---------------------
+
+.. autoclass:: black.ProtoComment
+    :members:
+
 :class:`Report`
 ---------------
 
@@ -38,17 +44,33 @@
     :members:
     :special-members: __str__
 
-:class:`UnformattedLines`
--------------------------
+:class:`Visitor`
+----------------
 
-.. autoclass:: black.UnformattedLines
+.. autoclass:: black.Visitor
     :show-inheritance:
     :members:
-    :special-members: __str__
 
-:class:`Visitor`
+Enums
+=====
+
+:class:`Changed`
 ----------------
 
-.. autoclass:: black.Visitor
+.. autoclass:: black.Changed
+    :show-inheritance:
+    :members:
+
+:class:`FileMode`
+-----------------
+
+.. autoclass:: black.FileMode
+    :show-inheritance:
+    :members:
+
+:class:`WriteBack`
+------------------
+
+.. autoclass:: black.WriteBack
     :show-inheritance:
     :members:

diff --git a/docs/reference/reference_exceptions.rst b/docs/reference/reference_exceptions.rst
index 46b042eddb3e45db242414cd418f40673dcd02ef..517249fa4ce68e0e34d4d9755dde7b9172c8d4b2 100644 (file)
--- a/docs/reference/reference_exceptions.rst
+++ b/docs/reference/reference_exceptions.rst
@@ -7,10 +7,6 @@
 
 .. autoexception:: black.CannotSplit
 
-.. autoexception:: black.FormatError
-
-.. autoexception:: black.FormatOn
-
-.. autoexception:: black.FormatOff
-
 .. autoexception:: black.NothingChanged
+
+.. autoexception:: black.InvalidInput

diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst
index 3e061b80ef9c32da8859fcbebb12440be772a18a..ccea313be20cdee83546b85316b768f8d1af92b1 100644 (file)
--- a/docs/reference/reference_functions.rst
+++ b/docs/reference/reference_functions.rst
@@ -12,6 +12,8 @@ Assertions and checks
 
 .. autofunction:: black.assert_stable
 
+.. autofunction:: black.can_be_split
+
 .. autofunction:: black.can_omit_invisible_parens
 
 .. autofunction:: black.is_empty_tuple
@@ -59,8 +61,12 @@ File operations
 
 .. autofunction:: black.dump_to_file
 
+.. autofunction:: black.find_project_root
+
 .. autofunction:: black.gen_python_files_in_dir
 
+.. autofunction:: black.read_pyproject_toml
+
 Parsing
 -------
 
@@ -73,6 +79,8 @@ Parsing
 Split functions
 ---------------
 
+.. autofunction:: black.bracket_split_succeeded_or_raise
+
 .. autofunction:: black.delimiter_split
 
 .. autofunction:: black.left_hand_split
@@ -83,13 +91,13 @@ Split functions
 
 .. autofunction:: black.split_line
 
-.. autofunction:: black.bracket_split_succeeded_or_raise
-
 Caching
 -------
 
 .. autofunction:: black.filter_cached
 
+.. autofunction:: black.get_cache_file
+
 .. autofunction:: black.get_cache_info
 
 .. autofunction:: black.read_cache
@@ -103,8 +111,22 @@ Utilities
 
     Pretty-print the lib2to3 AST of a given string of `code`.
 
+.. autofunction:: black.cancel
+
+.. autofunction:: black.child_towards
+
+.. autofunction:: black.container_of
+
+.. autofunction:: black.convert_one_fmt_off_pair
+
 .. autofunction:: black.diff
 
+.. autofunction:: black.dont_increase_indentation
+
+.. autofunction:: black.format_float_or_int_string
+
+.. autofunction:: black.format_int_string
+
 .. autofunction:: black.ensure_visible
 
 .. autofunction:: black.enumerate_reversed
@@ -113,20 +135,42 @@ Utilities
 
 .. autofunction:: black.generate_comments
 
+.. autofunction:: black.generate_ignored_nodes
+
+.. autofunction:: black.generate_trailers_to_omit
+
+.. autofunction:: black.get_future_imports
+
+.. autofunction:: black.list_comments
+
 .. autofunction:: black.make_comment
 
 .. autofunction:: black.maybe_make_parens_invisible_in_atom
 
 .. autofunction:: black.max_delimiter_priority_in_atom
 
+.. autofunction:: black.normalize_fmt_off
+
+.. autofunction:: black.normalize_numeric_literal
+
 .. autofunction:: black.normalize_prefix
 
+.. autofunction:: black.normalize_string_prefix
+
 .. autofunction:: black.normalize_string_quotes
 
 .. autofunction:: black.normalize_invisible_parens
 
+.. autofunction:: black.patch_click
+
 .. autofunction:: black.preceding_leaf
 
+.. autofunction:: black.re_compile_maybe_verbose
+
+.. autofunction:: black.should_explode
+
+.. autofunction:: black.shutdown
+
 .. autofunction:: black.sub_twice
 
 .. autofunction:: black.whitespace