diff --git a/config/flake8.ini b/config/flake8.ini new file mode 100644 index 0000000..1db6539 --- /dev/null +++ b/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 diff --git a/duties.py b/duties.py index c085ff8..4b502dd 100644 --- a/duties.py +++ b/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). diff --git a/pyproject.toml b/pyproject.toml index 7816ebc..47ae1a4 100644 --- a/pyproject.toml +++ b/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 -] diff --git a/src/mkdocs_autorefs/plugin.py b/src/mkdocs_autorefs/plugin.py index 56073c3..3d5ba32 100644 --- a/src/mkdocs_autorefs/plugin.py +++ b/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][]`. diff --git a/src/mkdocs_autorefs/references.py b/src/mkdocs_autorefs/references.py index ebe3b56..067284f 100644 --- a/src/mkdocs_autorefs/references.py +++ b/src/mkdocs_autorefs/references.py @@ -10,8 +10,7 @@ from markdown.inlinepatterns import REFERENCE_RE, ReferenceInlineProcessor AUTO_REF_RE = re.compile(r'[^"<>]*)\1>(?P.*?)</span>') -""" -A regular expression to match mkdocs-autorefs' special reference markers +"""A regular expression to match mkdocs-autorefs' special reference markers in the [`on_post_page` hook][mkdocs_autorefs.plugin.AutorefsPlugin.on_post_page]. """ @@ -28,8 +27,7 @@ def __init__(self, *args, **kwargs): # noqa: D107 # https://github.com/Python-Markdown/markdown/blob/8e7528fa5c98bf4652deb13206d6e6241d61630b/markdown/inlinepatterns.py#L780 def handleMatch(self, m, data) -> Union[Element, EvalIDType]: # noqa: N802 (parent's casing) - """ - Handle an element that matched. + """Handle an element that matched. Arguments: m: The match object. @@ -56,8 +54,7 @@ def handleMatch(self, m, data) -> Union[Element, EvalIDType]: # noqa: N802 (par return self.makeTag(identifier, text), m.start(0), end def evalId(self, data: str, index: int, text: str) -> EvalIDType: # noqa: N802 (parent's casing) - """ - Evaluate the id portion of `[ref][id]`. + """Evaluate the id portion of `[ref][id]`. If `[ref][]` use `[ref]`. @@ -77,8 +74,7 @@ def evalId(self, data: str, index: int, text: str) -> EvalIDType: # noqa: N802 return identifier, end, True def makeTag(self, identifier: str, text: str) -> Element: # noqa: N802,W0221 (parent's casing, different params) - """ - Create a tag that can be matched by `AUTO_REF_RE`. + """Create a tag that can be matched by `AUTO_REF_RE`. Arguments: identifier: The identifier to use in the HTML property. @@ -94,8 +90,7 @@ def makeTag(self, identifier: str, text: str) -> Element: # noqa: N802,W0221 (p def relative_url(url_a: str, url_b: str) -> str: - """ - Compute the relative path from URL A to URL B. + """Compute the relative path from URL A to URL B. Arguments: url_a: URL A. @@ -121,8 +116,7 @@ def relative_url(url_a: str, url_b: str) -> str: def fix_ref(url_mapper: Callable[[str], str], from_url: str, unmapped: List[str]) -> Callable: - """ - Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub). + """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub). In our context, we match Markdown references and replace them with HTML links. @@ -163,8 +157,7 @@ def fix_refs( from_url: str, url_mapper: Callable[[str], str], ) -> Tuple[str, List[str]]: - """ - Fix all references in the given HTML text. + """Fix all references in the given HTML text. Arguments: html: The text to fix. @@ -184,8 +177,7 @@ class AutorefsExtension(Extension): """Extension that inserts auto-references in Markdown.""" def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name) - """ - Register the extension. + """Register the extension. Add an instance of our [`AutoRefInlineProcessor`][mkdocs_autorefs.references.AutoRefInlineProcessor] to the Markdown parser. diff --git a/tests/test_references.py b/tests/test_references.py index fd58791..bef1d27 100644 --- a/tests/test_references.py +++ b/tests/test_references.py @@ -31,20 +31,12 @@ ], ) def test_relative_url(current_url, to_url, href_url): - """ - Compute relative URLs correctly. - - Arguments: - current_url: The URL of the source page. - to_url: The URL of the target page. - href_url: The relative URL to put in the `href` HTML field. - """ + """Compute relative URLs correctly.""" assert relative_url(current_url, to_url) == href_url def run_references_test(url_map, source, output, unmapped=None, from_url="page.html"): - """ - Help running tests about references. + """Help running tests about references. Arguments: url_map: The URL mapping.