Cannot build docs about mne-python

[larsoner]

No need for FreeSurfer -- the error is subjects_dir does not exist so It wants a valid subjects_dir. In principle it shouldn't, but an easy workaround is to mne.datasets.fetch_fsaverage then set your SUBJECTS_DIR in your MNE config to point there.

Then we should also look into why it even tries to run the function, it shouldn't do that when in --help mode

[cbrnr]

I've created the temp folder for now, but I really shouldn't have to do that. I didn't want to download the dataset and change the config, but just creating the folder was enough (I think).

Not sure what you mean by --help mode...

And I'm getting another error now:

...
generating MNE command help ... [100%] mne_what.py
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 967 source files that are out of date
updating environment: [new config] 968 added, 0 changed, 0 removed
reading sources... [  3%] auto_examples/datasets/brainstorm_data
Traceback (most recent call last):
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/cmd/build.py", line 298, in build_main
    app.build(args.force_all, args.filenames)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 293, in build_update
    self.build(to_build,
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 313, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 420, in read
    self._read_serial(docnames)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 441, in _read_serial
    self.read_doc(docname)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 498, in read_doc
    publisher.publish()
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/io.py", line 105, in read
    self.parse()
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/parsers.py", line 81, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 3024, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
                   ^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2799, in text
    paragraph, literalnext = self.paragraph(lines, startline)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 416, in paragraph
    textnodes, messages = self.inline_text(text, lineno)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 425, in inline_text
    nodes, messages = self.inliner.parse(text, lineno,
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 649, in parse
    before, inlines, remaining, sysmessages = method(self, match,
                                              ^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 792, in interpreted_or_phrase_ref
    nodelist, messages = self.interpreted(rawsource, escaped, role,
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 889, in interpreted
    nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/util/docutils.py", line 549, in __call__
    return super().__call__(name, rawtext, text, lineno, inliner, options, content)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/util/docutils.py", line 487, in __call__
    return self.run()
           ^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/roles.py", line 109, in run
    return self.create_xref_node()
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinx/roles.py", line 143, in create_xref_node
    return self.result_nodes(self.inliner.document, self.env, refnode, is_ref=True)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/sphinxcontrib/bibtex/foot_roles.py", line 75, in result_nodes
    formatted_entry = style.format_entry(label="", entry=entry)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/formatting/__init__.py", line 72, in format_entry
    text = get_template(entry).format_data(context)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/formatting/__init__.py", line 32, in toplevel
    return join(sep=Symbol('newblock')) [children].format_data(data)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 176, in join
    parts = [part for part in _format_list(children, data) if part]
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 150, in <genexpr>
    return (_format_data(part, data) for part in list_)
            ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 146, in _format_data
    return f(data)
           ^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 237, in sentence
    text = join(sep) [children].format_data(data)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 176, in join
    parts = [part for part in _format_list(children, data) if part]
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 150, in <genexpr>
    return (_format_data(part, data) for part in list_)
            ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 146, in _format_data
    return f(data)
           ^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/template.py", line 284, in names
    formatted_names = [style.format_name(person, style.abbreviate_names) for person in persons]
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/style/names/plain.py", line 63, in format
    name_part(tie=True, abbr=abbr)[person.rich_first_names + person.rich_middle_names],
                                   ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/database/__init__.py", line 824, in rich_first_names
    return [Text.from_latex(name) for name in self.first_names]
            ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/pybtex/richtext.py", line 818, in from_latex
    import latexcodec  # noqa
    ^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/latexcodec/__init__.py", line 1, in <module>
    import latexcodec.codec
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/latexcodec/codec.py", line 218, in <module>
    _LATEX_UNICODE_TABLE = LatexUnicodeTable(lexer.LatexIncrementalDecoder())
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/latexcodec/codec.py", line 126, in __init__
    self.register_all()
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/latexcodec/codec.py", line 149, in register_all
    for trans in load_unicode_latex_table():
  File "/Users/clemens/.pyenv/versions/3.12.2/envs/mne/lib/python3.12/site-packages/latexcodec/codec.py", line 102, in load_unicode_latex_table
    with pkg_resources.open_text('latexcodec', 'table.txt') as datafile:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/clemens/.pyenv/versions/3.12.2/lib/python3.12/importlib/resources/_legacy.py", line 18, in wrapper
    warnings.warn(
DeprecationWarning: open_text is deprecated. Use files() instead. Refer to https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration advice.

Exception occurred:
  File "/Users/clemens/.pyenv/versions/3.12.2/lib/python3.12/importlib/resources/_legacy.py", line 18, in wrapper
    warnings.warn(
DeprecationWarning: open_text is deprecated. Use files() instead. Refer to https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration advice.
The full traceback has been saved in /var/folders/03/3fgzbmm55ts28rzstwm1750h0000gn/T/sphinx-err-zw3_62al.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html-noplot] Error 2

[larsoner]

Try updating to latest latexcodec

[larsoner]

Hah actually latest latexcodec seems to have the problem. 2.something didn't. Just add the warning to doc/conf.py warnings list

mne-python/doc/conf.py

Line 1364 in 52d9a9b

r"\nPyarrow will become a required dependency of pandas.*",

[cbrnr]

Just add the warning to doc/conf.py warnings list

OK, that worked, thanks. How would you like to proceed in order to fix this issue/these issues?

[larsoner]

I've created the temp folder for now, but I really shouldn't have to do that. I didn't want to download the dataset and change the config, but just creating the folder was enough (I think).

In your case I think it was essentially that your mne-python config was invalid -- it pointed to a directory that did not exist. So the error might have been a bit cryptic but ultimately perhaps helpful in that it indicated something was indeed wrong. I'd suggest just to delete the config value directly or use mne.set_config("SUBJECTS_DIR", None) to have MNE do it for you. I'll open a PR to improve the message

How would you like to proceed in order to fix this issue/these issues?

Any PR could include this new ignore in the ignore lines. I can put it in my config-checking one.

[cbrnr]

In your case I think it was essentially that your mne-python config was invalid -- it pointed to a directory that did not exist.

Correct, thanks for improving the error message! And yes, please go ahead and include the new ignore.

[cbrnr]

Fixed by #12567.