I thus propose to place both folders under docs and name the ouput folder examples and name the input folder examples_inputs

I like this idea a lot, but would suggest a small tweak: maybe examples_source_files instead of examples_input? To me examples_input is still a bit unclear (e.g., it could be "examples about the kinds of input my package accepts"). Another idea is to call it sg_examples or similar (to more clearly signal these are files meant for sphinx gallery's consumption).

(sorry if this is too bikesheddy, if you don't immediately agree that either suggestion is an improvement, feel free to disregard).

Happy to have it changed, though will need to update in a fair few places: https://github.com/search?q=repo%3Asphinx-gallery%2Fsphinx-gallery%20auto_example&type=code

Input: Preference for something short, sg_examples, examples_src ..?

Output: The new URL is nice but I wonder if it would cause confusion if someone was e.g., looking at how SG is setup in an existing project?

I like examples_src.

I wonder if it would cause confusion if someone was e.g., looking at how SG is setup in an existing project?

Just checked the output folder: Looking at
https://github.com/sphinx-gallery/sphinx-gallery/blob/master/README.rst#who-uses-sphinx-gallery, out of 27 directly linked galleries, 11 use the current auto_examples, 8 have changed to examples already by themselves. The rest have other names, e.g. tutorials or gallery. So, changing our docs is not that foreign to existing usages.

Thanks for doing the numbers, I'm okay with the change. @larsoner WDYT?

Side notes:

1. Likely, we should also change the example structure in the sphinx-gallery repo itself to be a role model. That's quite a bit of code churn, but not really complicated. Problably best to do this separtely from the doc changes to keep reviews simpler.
2. The key examples_dirs in sphinx_gallery_conf is not ideal as well. examples does not logically connect to the inputs. The outputs are logically still examples. Additionally, There can be other inputs like tutorials. I always find it hard to understand what a configuration like this means:

   sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples', '../tutorials'],
    'gallery_dirs': ['auto_examples', 'tutorials'],
   }
   

   Would there be appetite to go into clearer naming here as well - of course as a separte topic and with suitable backward compatibility.

When I started working on SG the names examples_dirs and gallery_dirs did not connotate 'input'/'output', but now I've gotten used to the names 🤷

I agree the names could be improved but it would be a backwards incompatible change, which we tend not to do. @larsoner ?

Likely, we should also change the example structure in the sphinx-gallery repo itself to be a role model. That's quite a bit of code churn, but not really complicated. Problably best to do this separtely from the doc changes to keep reviews simpler.

git mv is pretty easy to see/review even if it's tens of files, so it could be part of the same PR if you want.

Would there be appetite to go into clearer naming here as well - of course as a separte topic and with suitable backward compatibility.

I agree the names could be improved but it would be a backwards incompatible change, which we tend not to do. @larsoner ?

Well I suppose we're on the topic well enough... Agreed we don't want to break existing code for this. But taking @timhoffm's hint about backward compat we could for example allow aliases, like you either specify the pair examples_dirs/gallery_dirs (old style) or the pair examples_input/examples_output (new style), but not both. I don't think this will lead to much additional code and would improve readability.

As a side point, I think the current naming stems from the projects having existing examples/ scripts that they provided for their users, presumably (?) in the project root because they wanted people to be able to find, download, and run them easily themselves. Then (like 10+ years ago!) the idea was, why not render these into a gallery on the website and in the docs? sphinx_gallery came into existence to do that job. So examples_dirs and gallery_dirs follows naturally from that framing of the problem and evolution of the code. Thinking about it as input and output is perhaps more natural if you start a project from scratch nowadays, though, so I'm not opposed to having a more readable alias.