chore: Migrate to flake8, normalize docstrings (#3)

Author: oprypin

config/flake8.ini

@@ -0,0 +1,49 @@
+[flake8]
+exclude = fixtures,docs,site
+max-line-length = 132
+strictness = long
+docstring-convention = google
+ban-relative-imports = true
+ignore =
+    # redundant with W0622 (builtin override), which is more precise about line number
+    A001
+    # missing docstring in magic method
+    D105
+    # whitespace before ':' (incompatible with Black)
+    E203
+    # redundant with E0602 (undefined variable)
+    F821
+    # black already deals with quoting
+    Q000
+    # use of assert
+    S101
+    # we are not parsing XML
+    S405
+    # line break before binary operator (incompatible with Black)
+    W503
+    # two-lowercase-letters variable DO conform to snake_case naming style
+    C0103
+    # redunant with D102 (missing docstring)
+    C0116
+    # line too long
+    C0301
+    # too many instance attributes
+    R0902
+    # too few public methods
+    R0903
+    # too many public methods
+    R0904
+    # too many branches
+    R0912
+    # too many methods
+    R0913
+    # too many local variables
+    R0914
+    # too many statements
+    R0915
+    # redundant with F401 (unused import)
+    W0611
+    # lazy formatting for logging calls
+    W1203
+    # short name
+    VNE001

duties.py

@@ -20,8 +20,7 @@
 
 
 def latest(lines: List[str], regex: Pattern) -> Optional[str]:
-    """
-    Return the last released version.
+    """Return the last released version.
 
     Arguments:
         lines: Lines of the changelog file.
@@ -38,8 +37,7 @@ def latest(lines: List[str], regex: Pattern) -> Optional[str]:
 
 
 def unreleased(versions: List[Version], last_release: str) -> List[Version]:
-    """
-    Return the most recent versions down to latest release.
+    """Return the most recent versions down to latest release.
 
     Arguments:
         versions: All the versions (released and unreleased).
@@ -55,8 +53,7 @@ def unreleased(versions: List[Version], last_release: str) -> List[Version]:
 
 
 def read_changelog(filepath: str) -> List[str]:
-    """
-    Read the changelog file.
+    """Read the changelog file.
 
     Arguments:
         filepath: The path to the changelog file.
@@ -69,8 +66,7 @@ def read_changelog(filepath: str) -> List[str]:
 
 
 def write_changelog(filepath: str, lines: List[str]) -> None:
-    """
-    Write the changelog file.
+    """Write the changelog file.
 
     Arguments:
         filepath: The path to the changelog file.
@@ -87,8 +83,7 @@ def update_changelog(
     template_url: str,
     commit_style: str,
 ) -> None:
-    """
-    Update the given changelog file in place.
+    """Update the given changelog file in place.
 
     Arguments:
         inplace_file: The file to update in-place.
@@ -120,8 +115,7 @@ def update_changelog(
 
 @duty
 def changelog(ctx):
-    """
-    Update the changelog in-place with latest commits.
+    """Update the changelog in-place with latest commits.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -142,8 +136,7 @@ def changelog(ctx):
 
 @duty(pre=["check_code_quality", "check_types", "check_docs", "check_dependencies"])
 def check(ctx):  # noqa: W0613 (no use for the context argument)
-    """
-    Check it all!
+    """Check it all!
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -152,20 +145,18 @@ def check(ctx):  # noqa: W0613 (no use for the context argument)
 
 @duty
 def check_code_quality(ctx, files=PY_SRC):
-    """
-    Check the code quality.
+    """Check the code quality.
 
     Arguments:
         ctx: The context instance (passed automatically).
         files: The files to check.
     """
-    ctx.run(f"flakehell lint {files}", title="Checking code quality", pty=PTY)
+    ctx.run(f"flake8 --config=config/flake8.ini {files}", title="Checking code quality", pty=PTY)
 
 
 @duty
 def check_dependencies(ctx):
-    """
-    Check for vulnerabilities in dependencies.
+    """Check for vulnerabilities in dependencies.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -195,8 +186,7 @@ def check_dependencies(ctx):
 
 @duty
 def check_docs(ctx):
-    """
-    Check if the documentation builds correctly.
+    """Check if the documentation builds correctly.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -208,8 +198,7 @@ def check_docs(ctx):
 
 @duty
 def check_types(ctx):
-    """
-    Check that the code is correctly typed.
+    """Check that the code is correctly typed.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -219,8 +208,7 @@ def check_types(ctx):
 
 @duty(silent=True)
 def clean(ctx):
-    """
-    Delete temporary files.
+    """Delete temporary files.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -238,8 +226,7 @@ def clean(ctx):
 
 @duty
 def docs(ctx):
-    """
-    Build the documentation locally.
+    """Build the documentation locally.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -249,8 +236,7 @@ def docs(ctx):
 
 @duty
 def docs_serve(ctx, host="127.0.0.1", port=8000):
-    """
-    Serve the documentation (localhost:8000).
+    """Serve the documentation (localhost:8000).
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -262,8 +248,7 @@ def docs_serve(ctx, host="127.0.0.1", port=8000):
 
 @duty
 def docs_deploy(ctx):
-    """
-    Deploy the documentation on GitHub pages.
+    """Deploy the documentation on GitHub pages.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -273,8 +258,7 @@ def docs_deploy(ctx):
 
 @duty
 def format(ctx):  # noqa: W0622 (we don't mind shadowing the format builtin)
-    """
-    Run formatting tools on the code.
+    """Run formatting tools on the code.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -290,8 +274,7 @@ def format(ctx):  # noqa: W0622 (we don't mind shadowing the format builtin)
 
 @duty
 def release(ctx, version):
-    """
-    Release a new Python package.
+    """Release a new Python package.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -311,8 +294,7 @@ def release(ctx, version):
 
 @duty(silent=True)
 def coverage(ctx):
-    """
-    Report coverage as text and HTML.
+    """Report coverage as text and HTML.
 
     Arguments:
         ctx: The context instance (passed automatically).
@@ -323,8 +305,7 @@ def coverage(ctx):
 
 @duty
 def test(ctx, cleancov: bool = True, match: str = ""):
-    """
-    Run the test suite.
+    """Run the test suite.
 
     Arguments:
         ctx: The context instance (passed automatically).

pyproject.toml

@@ -71,37 +71,3 @@ balanced_wrapping = true
 default_section = "THIRDPARTY"
 known_first_party = "mkdocs_autorefs"
 include_trailing_comma = true
-
-[tool.flakehell]
-format = "colored"
-max_line_length = 132
-show_source = false
-exclude = ["tests/fixtures"]
-
-[tool.flakehell.plugins]
-"*" = [
-    "+*",
-    "-RST*",  # we write docstrings in markdown, not rst
-    "-A001",  # redundant with W0622 (builtin override), which is more precise about line number
-    "-D105",  # missing docstring in magic method
-    "-D212",  # multi-line docstring summary should start at the first line
-    "-E203",  # whitespace before ‘:’ (incompatible with Black)
-    "-F821",  # redundant with E0602 (undefined variable)
-    "-Q000",  # black already deals with quoting
-    "-S101",  # use of assert
-    "-S405",  # we are not parsing XML
-    "-W503",  # line break before binary operator (incompatible with Black)
-    "-C0103", # two-lowercase-letters variable DO conform to snake_case naming style
-    "-C0116",  # redunant with D102 (missing docstring)
-    "-C0301",  # line too long
-    "-R0902",  # too many instance attributes
-    "-R0903",  # too few public methods
-    "-R0904",  # too many public methods
-    "-R0912",  # too many branches
-    "-R0913",  # too many methods
-    "-R0914",  # too many local variables
-    "-R0915",  # too many statements
-    "-W0611",  # redundant with F401 (unused import)
-    "-W1203",  # lazy formatting for logging calls
-    "-VNE001",  # short name
-]

src/mkdocs_autorefs/plugin.py

@@ -1,5 +1,4 @@
-"""
-This module contains the "mkdocs-autorefs" plugin.
+"""This module contains the "mkdocs-autorefs" plugin.
 
 After each page is processed by the Markdown converter, this plugin stores absolute URLs of every HTML anchors
 it finds to later be able to fix unresolved references.
@@ -27,8 +26,7 @@
 
 
 class AutorefsPlugin(BasePlugin):
-    """
-    An `mkdocs` plugin.
+    """An `mkdocs` plugin.
 
     This plugin defines the following event hooks:
 
@@ -50,8 +48,7 @@ def __init__(self) -> None:
         self.get_fallback_anchor: Callable[[str], Optional[str]] = lambda identifier: None
 
     def register_anchor(self, page: str, anchor: str):
-        """
-        Register that an anchor corresponding to an identifier was encountered when rendering the page.
+        """Register that an anchor corresponding to an identifier was encountered when rendering the page.
 
         Arguments:
             page: The relative URL of the current page. Examples: `'foo/bar/'`, `'foo/index.html'`
@@ -60,8 +57,7 @@ def register_anchor(self, page: str, anchor: str):
         self._url_map[anchor] = f"{page}#{anchor}"
 
     def get_item_url(self, anchor: str) -> str:
-        """
-        Return a site-relative URL with anchor to the identifier, if it's present anywhere.
+        """Return a site-relative URL with anchor to the identifier, if it's present anywhere.
 
         Arguments:
             anchor: The anchor (without '#').
@@ -81,8 +77,7 @@ def get_item_url(self, anchor: str) -> str:
             raise
 
     def on_config(self, config: Config, **kwargs) -> Config:  # noqa: W0613,R0201 (unused arguments, cannot be static)
-        """
-        Instantiate our Markdown extension.
+        """Instantiate our Markdown extension.
 
         Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
         In this hook, we instantiate our [`AutorefsExtension`][mkdocs_autorefs.references.AutorefsExtension]
@@ -100,8 +95,7 @@ def on_config(self, config: Config, **kwargs) -> Config:  # noqa: W0613,R0201 (u
         return config
 
     def on_page_markdown(self, markdown: str, page: Page, **kwargs) -> str:  # noqa: W0613 (unused arguments)
-        """
-        Remember which page is the current one.
+        """Remember which page is the current one.
 
         Arguments:
             markdown: Input Markdown.
@@ -115,8 +109,7 @@ def on_page_markdown(self, markdown: str, page: Page, **kwargs) -> str:  # noqa:
         return markdown
 
     def on_page_content(self, html: str, page: Page, **kwargs) -> str:  # noqa: W0613 (unused arguments)
-        """
-        Map anchors to URLs.
+        """Map anchors to URLs.
 
         Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).
         In this hook, we map the IDs of every anchor found in the table of contents to the anchors absolute URLs.
@@ -138,8 +131,7 @@ def on_page_content(self, html: str, page: Page, **kwargs) -> str:  # noqa: W061
         return html
 
     def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
-        """
-        Recurse on every anchor to map its ID to its absolute URL.
+        """Recurse on every anchor to map its ID to its absolute URL.
 
         This method populates `self.url_map` by side-effect.
 
@@ -152,8 +144,7 @@ def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
             self.map_urls(base_url, child)
 
     def on_post_page(self, output: str, page: Page, **kwargs) -> str:  # noqa: W0613 (unused arguments)
-        """
-        Fix cross-references.
+        """Fix cross-references.
 
         Hook for the [`on_post_page` event](https://www.mkdocs.org/user-guide/plugins/#on_post_page).
         In this hook, we try to fix unresolved references of the form `[title][identifier]` or `[identifier][]`.