Trying to understand this, it looks like the local variablerst_dir is used generate the path that is eventually passed to

I am also a little confused by why this is needed. Isautodoc2 generating rst in a non-final location, running a pass of processing on them, and then moving the output someplace else?

We are trying to infer the build directory, is there a better way to get that directly?

Trying to understand this, it looks like the local variablerst_dir is used generate the path that is eventually passed to

matplotlib/lib/matplotlib/sphinxext/plot_directive.py

Lines 916 to 926 in3b30f47

	result=jinja2.Template(config.plot_templateortemplate).render(
	default_fmt=default_fmt,
	build_dir=build_dir_link,
	src_name=src_name,
	multi_image=len(images)>1,
	options=opts,
	srcset=srcset,
	images=images,
	source_code=source_code,
	html_show_formats=config.plot_html_show_formatsandlen(images),
	caption=caption)

asbuild_dir=build_dir_link. Given that, I think that if we do take this the name should be something likeplot_build_directory to be clearer about what it is actually affecting (rst_dir makes sense in the code as it is extracted from the path to the rst file).

Well this is not the build dir neither. Because the build directory is another place, but that also depends on the filename… For example, the build dir’s default location with my setup is put inside the docs/source dir, not the docs/build dir, which seems weird to me too.

I am also a little confused by why this is needed. Isautodoc2 generating rst in a non-final location, running a pass of processing on them, and then moving the output someplace else?

Autodoc2 generates source files, but is hardly configurable. So a solution could be to modify their extension by adding more flexibility, or adding some kind of post processor.

To me, the easiest solution was just to add a new configuration variable to the matplotlib extension. In my opinion, but the matplotlib extension and the autodoc2 extension could be a bit more configurable :)

We are trying to infer the build directory, is there a better way to get that directly?

Maybe, I tried to read a bit the code but it is quite hard to determine the implication of each variable :’-)

I have a memory of leaving another comment here but apparently not 😞

How does this interact with#24205 and is this related to the issue discussed in
#24005

I am still very skeptical of this as-is.

I think the analysis we need is a flow diagram of how the whole sphinx build process works here (I think we generate rst + images that get put in the source in an early step and then a late step goes discovers them and then generates the html which is why the "builddir" of this step is the "sourcedir" of the next step). There is clearly something wrong with the logic to generate the various paths (and the internal variable names could be improved), but adding a global setting to reach in and override a particular bit of the logic is unlikely to be the best solution. Even if we do have to do something like that, I remain skeptical that this is is the right place to put the knob.

I was just working on the directive so I will take a look in the next day or so.

What happens is explained athttps://github.com/matplotlib/matplotlib/blame/67c4bb3986e3bccfcebc69d1177007d4aa4483d2/lib/matplotlib/sphinxext/plot_directive.py#L154. I was going to say it is well-explained, but I wrote it, so I guess I think just like the author.

If we have an rst file indoc/my_info/boo.rst then the directive makes a plot inbuild/plot_directive/my_info/boo-1.png, and while it makes the html forbuild/my_info/boo.html it turns the boo.rst plot into a.. figure: directive that then puts the png into the webpage. This is done at

build_dir = os.path.join(os.path.dirname(setup.app.doctreedir),                             'plot_directive',                             source_rel_dir)

For our API data, it generates rst files underdoc/api and any plot directives follow the same procedure as above.

I don't understand why the current PR wants to changerst_dir. That is only used for linking. I'd have to better understand where autodoc2 is trying to put things to understand what the issue is. But I'd have thought it would build a subdirectory of rst files under yourdoc directory, and then things should just work. If thats not the case, maybe@jeertmans can explain further.

If think the issue here is thatautodoc2 actually generates the.rst files at build time, unlikeautodoc that is just a Sphinx directive. When I have time, I'd like to work on a MWE, so it's easier to understand when it fails to work as expected.

I've moved to draft, but feel free to put back in the queue if you think this is ready,.

Hi@jklymak, I am marking as ready as I have finally found some time to create a MWE:https://github.com/jeertmans/matplotlib-mwe-26099.

GitHub actions are automatically run, and thelatest ones show that apply the fix is necessary to build the documentation correctly.

See build logs when the fix is not applied:

/home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/src/matplotlib_mwe_26099/__init__.py:12: WARNING: image file not readable: docs/src/matplotlib_mwe_26099/__init__-2.png [image.not_readable]/home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/src/matplotlib_mwe_26099/__init__.py:-10: WARNING: download file not readable: /home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/docs/source/docs/src/matplotlib_mwe_26099/__init__-2.py [download.not_readable]/home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/src/matplotlib_mwe_26099/__init__.py:-10: WARNING: download file not readable: /home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/docs/source/docs/src/matplotlib_mwe_26099/__init__-2.png [download.not_readable]/home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/src/matplotlib_mwe_26099/__init__.py:-10: WARNING: download file not readable: /home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/docs/source/docs/src/matplotlib_mwe_26099/__init__-2.hires.png [download.not_readable]/home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/src/matplotlib_mwe_26099/__init__.py:-10: WARNING: download file not readable: /home/runner/work/matplotlib-mwe-26099/matplotlib-mwe-26099/docs/source/docs/src/matplotlib_mwe_26099/__init__-2.pdf [download.not_readable]looking for now-outdated files... none found