Tracking: Upgrade docstring linting

[dangotbanned]

Issues

• Implement rules in darglint astral-sh/ruff#458
• Implement pydoclint astral-sh/ruff#12434

Related

• docs: Start using Darglint #1387
• https://github.com/jsh9/pydoclint
• https://docs.astral.sh/ruff/rules/#pydoclint-doc
• https://docs.astral.sh/ruff/settings/#lintpydoclint

Description

We're currently using darglint, which is a flake8 plugin that was archived 2½ years ago.
Our .pre-commit-config.yaml lists a pretty old ruff issue, but there seems to have been progress made in a more recent issue.

narwhals/.pre-commit-config.yaml

Lines 24 to 28 in f47ad1f

	- repo: https://github.com/pycqa/flake8
	rev: '7.2.0' # todo: remove once https://github.com/astral-sh/ruff/issues/458 is addressed
	hooks:
	- id: flake8
	additional_dependencies: [darglint==1.8.1, Flake8-pyproject]

I'm not sure if the functionality in (DOC) is enough for us yet, but switching to the actively maintained pydoclint seems like another option worth exploring.

Extra

I'd really like if we can find something that allows for cutting down on the repetition mentioned in (#1943 (comment))

E.g. here I just wanted to add a one-liner for context, but instead need to repeat so much redundant information for darglint 😞

narwhals/narwhals/utils.py

Lines 1658 to 1667 in f47ad1f

	def _into_arrow_table(data: IntoArrowTable, context: _FullContext, /) -> pa.Table:
	"""Guards `ArrowDataFrame.from_arrow` w/ safer imports.
	Arguments:
	data: Object which implements `__arrow_c_stream__`.
	context: Initialized compliant object.
	Returns:
	A PyArrow Table.
	"""