Skip to content

chore: Migrate to flake8, normalize docstrings #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pawamoy merged 1 commit into from
Apr 20, 2021
Merged

chore: Migrate to flake8, normalize docstrings #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions config/flake8.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
59 changes: 20 additions & 39 deletions duties.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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).
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand Down Expand Up @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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).
Expand Down
34 changes: 0 additions & 34 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
]
27 changes: 9 additions & 18 deletions src/mkdocs_autorefs/plugin.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -27,8 +26,7 @@


class AutorefsPlugin(BasePlugin):
"""
An `mkdocs` plugin.
"""An `mkdocs` plugin.

This plugin defines the following event hooks:

Expand All @@ -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'`
Expand All @@ -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 '#').
Expand All @@ -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]
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.

Expand All @@ -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][]`.
Expand Down
Loading