From 41368138bbc69fd805dfc931f165e9488fc9986c Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C5=81ukasz=20Langa?= Date: Tue, 18 Sep 2018 12:04:30 -0700 Subject: [PATCH] Fix documentation build --- black.py | 11 ++++++ docs/reference/reference_classes.rst | 36 +++++++++++++++---- docs/reference/reference_exceptions.rst | 8 ++--- docs/reference/reference_functions.rst | 48 +++++++++++++++++++++++-- 4 files changed, 88 insertions(+), 15 deletions(-) diff --git a/black.py b/black.py index d257563..f2c450c 100644 --- 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 d99057e..3af0b47 100644 --- 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 46b042e..517249f 100644 --- 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 3e061b8..ccea313 100644 --- 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 -- 2.39.5