mne-tools / mne-tools/mne-python

Adding ArrayLike from numpy as a type hint leads to doc build errors.

Open
#13,840 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

BUG
Dominant language
Python
Stars
3.5k
Forks
1.6k
Avg merge
1d 6h
Merged PRs (30d)
100

Description

Description of the problem

I'm trying to improve type hints in the /home/himan/projects/mne-python-issue13597/mne/preprocessing/ica.py file with something like this(one of the functions in that file):

  def get_explained_variance_ratio(
      self,
      inst: BaseRaw | BaseEpochs | Evoked,
      *,
      components: ArrayLike | int | None = None,
      ch_type: Literal["mag", "grad", "planar1", "planar2", "eeg"]
      | ArrayLike
      | None = None,
  ):

however the ArrayLike - sphinx is unable to resolve this ref properly. And give the following error:

 <unknown>:1: WARNING: py:class reference target not found:
  numpy._typing.ArrayLike [ref.class]
Link to data

No response

Expected results

Should build docs without the error described above and add proper ref to the ArrayLike.

Actual results

Throws an error and fails to resolve link.

Additional information

Discussion on this.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the annotations in mne/preprocessing/ica.py and reproduce the documentation build that emits the unresolved numpy._typing.ArrayLike warning. Read the NumPy ArrayLike typing reference and the project’s Sphinx configuration to determine how the reference should resolve; done means the docs build completes without that warning and links ArrayLike correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
numpy, python
Domain
build-system, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.