doc build error on windows

[drammock]

@CarinaFo ran into this error when building the docs locally on windows

The chromedriver version (99.0.4844.51) detected in PATH at C:\Program Files\chromedriver\chromedriver.exe might not be compatible with the detected chrome version (117.0.5938.134); currently, chromedriver 117.0.5938.149 is recommended for chrome 117., so it is advised to delete the driver in PATH and retry
Exception ignored in: <_io.FileIO name='nul' mode='wb' closefd=True>
Traceback (most recent call last):
  File "C:\Users\Carina\Documents\mne_howtocontribute_workshop\mne-python\doc\sphinxext\contrib_avatars.py", line 21, in generate_contrib_avatars
    driver = webdriver.Firefox(options=options)
    ^^^^^^
ResourceWarning: unclosed file <_io.BufferedWriter name='nul'>
C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\sphinx\events.py:97: ResourceWarning: unclosed file <_io.BufferedWriter name='nul'>
  results.append(listener.handler(self.app,args))
ResourceWarning: Enable tracemalloc to get the object allocation traceback

this did not kill the doc build process, but the following later error did:

Traceback (most recent call last):
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\sphinx\events.py", line 97, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\numpydoc\numpydoc.py", line 214, in mangle_docstrings
    report = validate(doc)
             ^^^^^^^^^^^^^
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\numpydoc\validate.py", line 617, in validate
    ignore_validation_comments = extract_ignore_validation_comments(
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\numpydoc\validate.py", line 145, in extract_ignore_validation_comments
    for token in tokenize.generate_tokens(file.readline):
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\tokenize.py", line 454, in _tokenize
    line = readline()
           ^^^^^^^^^^
  File "C:\Users\Carina\mambaforge\envs\mnedev\Lib\encodings\cp1252.py", line 23, in decode
    return codecs.charmap_decode(input,self.errors,decoding_table)[0]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 3922: character maps to <undefined>

The first error is related to selenium building the contributor avatars, and will need a bit of debugging (it's also popping open the browser, which it shouldn't --- supposed to be headless).

The second error can be avoided by doing export PYTHONUTF8=1 in gitbash before running the doc build make command. After that, we get a different error:

Traceback (most recent call last):
"C:\Users\Carina\mambaforge\envs\mnedev\Lib\site-packages\sphinx\events.py", line 97, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Carina\Documents\mne_howtocontribute_workshop\mne-python\doc\conf.py", line 1783, in make_redirects
    if fr_path.split("/")[-2] in (
       ~~~~~~^^^^
IndexError: list index out of range

[larsoner]

tokenize is almost certainly a NumpyDoc bug here:

https://github.com/numpy/numpydoc/blob/b4135ce76e722088e2975ec01ca61d7b69b4bad2/numpydoc/validate.py#L138-L140

We should use encoding="utf-8" probably to unify Unix + Windows. Can you open a numpydoc issue for that part?

[hoechenberger]

@larsoner Should we add PYTHONUTF8=1 to the conda environment deployed on Windows through our installers?

[drammock]

Can you open a numpydoc issue for that part?

numpy/numpydoc#510

[larsoner]

@larsoner Should we add PYTHONUTF8=1 to the conda environment deployed on Windows through our installers?

My initial reaction is "no" because doing more magic in our installers just delays confusion -- code will work in our installers but not in regular conda, venvs, etc. Better if people (and packages like numpydoc) fixe their code. But as @drammock pointed out in the numpydoc issue this will become standard in a couple of years in 3.15 so maybe it's okay in a future-proofing sense. 🤷

[drammock]

just a note that the first traceback (the ResourceWarning) is already fixed upstream by SeleniumHQ/selenium#12637. Since it doesn't actually halt the docbuild I think there's no action needed except to wait for a new selenium release.