From e6653ed77de5f05d905a5acc92793cb028d5d0bc Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 28 Sep 2026 21:15:12 +0000 Subject: [PATCH 1/2] [FIX] Load m2r2's mdinclude extension instead of importing MdInclude Port of neurostuff/NiMARE#1156 to PyMARE, which has the same broken conf.py. `docs/conf.py` imported `MdInclude` and wired the `mdinclude` directive up by hand. That import only ever worked on m2r2 <= 0.3.4, which shipped as a single `m2r2.py` module. 1.0.0 repackaged the project and moved the class to `m2r2.sphinx.directives`, so the package root has not exported it since; `doc` required `m2r2` unpinned, so the docs build breaks as soon as the resolver picks up a 1.x or later release: ImportError: cannot import name 'MdInclude' from 'm2r2' 1.1.0 added an `m2r2.mdinclude` extension whose `setup()` registers the same five config values and the same `mdinclude` directive that conf.py registered by hand, so load that instead and drop the manual block. Both halves have to change together: leaving the manual registration in place alongside the extension raises `Config value 'no_underscore_emphasis' already present`. It is `m2r2.mdinclude` rather than plain `m2r2` because the full extension also registers a source parser for `.md` files, which would collide with recommonmark. Requires m2r2 >= 1.1 for the submodule, so `doc` now pins that floor -- without it the resolver could pick 1.0.x, where neither the old import nor the new extension exists. `mdinclude` is used by docs/contributing.rst. Verified by building the real docs with this conf against m2r2 2.1.0: the page renders CONTRIBUTING.md (all eight of its headings), the build succeeds, and no m2r2 or mdinclude warnings are emitted -- the four remaining warnings are pre-existing and unrelated. Confirmed the old import still raises the ImportError above under that same m2r2. flake8 reports exactly the same two pre-existing findings in conf.py as it does on master. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013NtnctTrY9VtEm6AwSf2FS --- docs/conf.py | 14 ++++---------- setup.cfg | 2 +- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f0e9813..3a08e45 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,6 @@ from distutils.version import LooseVersion import sphinx -from m2r2 import MdInclude sys.path.insert(0, os.path.abspath("sphinxext")) sys.path.insert(0, os.path.abspath(os.path.pardir)) @@ -55,6 +54,10 @@ "sphinxarg.ext", # argparse "sphinxcontrib.bibtex", # for foot-citations "recommonmark", # markdown parser + # The `mdinclude` directive, for pulling .md files into .rst pages. Deliberately the + # submodule and not "m2r2": the full extension also registers a parser for .md source + # files, which collides with recommonmark above. + "m2r2.mdinclude", ] if LooseVersion(sphinx.__version__) < LooseVersion("1.4"): @@ -207,15 +210,6 @@ def setup(app): app.add_css_file("theme_overrides.css") app.add_css_file("nimare.css") app.connect("autodoc-process-docstring", generate_example_rst) - # Fix to https://github.com/sphinx-doc/sphinx/issues/7420 - # from https://github.com/life4/deal/commit/7f33cbc595ed31519cefdfaaf6f415dada5acd94 - # from m2r to make `mdinclude` work - app.add_config_value("no_underscore_emphasis", False, "env") - app.add_config_value("m2r_parse_relative_links", False, "env") - app.add_config_value("m2r_anonymous_references", False, "env") - app.add_config_value("m2r_disable_inline_math", False, "env") - app.add_config_value("m2r_use_mermaid", True, "env") - app.add_directive("mdinclude", MdInclude) def generate_example_rst(app, what, name, obj, options, lines): diff --git a/setup.cfg b/setup.cfg index 664b7c3..eae6f5b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -41,7 +41,7 @@ include = [options.extras_require] doc = - m2r2 + m2r2>=1.1 matplotlib mistune numpydoc From 427eeb46675c6377222a0fa5a3e6221ee842d6bf Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 28 Sep 2026 21:16:06 +0000 Subject: [PATCH 2/2] Ignore sphinx-gallery's execution-times file `docs/sg_execution_times.rst` is regenerated by sphinx-gallery on every docs build, holding the wall-clock timings of that particular run. It is a build artifact, like the already-ignored docs/generated/ and docs/auto_examples/ beside it, so it should never be committed. NiMARE ignores it; PyMARE did not, so a local docs build left it sitting untracked. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013NtnctTrY9VtEm6AwSf2FS --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index c50c9fb..16b5d93 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ docs/generated/ docs/modules/ docs/auto_examples/ +# sphinx-gallery writes per-example timings on every docs build. +docs/sg_execution_times.rst historical/ #