Thanks Quentin for this contribution!

I did some minor rewords while merging, but I left your core contribution intact.

I find the new docs a bit confusing so I'masking something to you.

Is the following current explanation:

When set to ``true``, the cache is stored in ``%kernel.cache_dir%/twig`` by default.However, if ``auto_reload`` is disabled and ``%kernel.build_dir%`` differs from``%kernel.cache_dir%``, the cache will be stored in ``%kernel.build_dir%/twig`` instead.

Equivalent to this simplified version?

When set to ``true``, the cache is stored in ``%kernel.cache_dir%/twig`` by default.However, if ``auto_reload`` is disabled the cache will be stored in``%kernel.build_dir%/twig`` instead.

I mean:

• Ifauto_reload is disabled:
  • Ifbuild_dir andcache_dir are different, thenbuild_dir is used
  • Ifbuild_dir andcache_dir are the same, thencache_dir is used. BUT, if they are the same, we're usingbuild_dir
  • So, we always usebuild_dir whenauto_reload is disabled, right?

Maybe I'm missing something here.

@javiereguiluz It's indeed a bit confusing, because the setup is a bit more convoluted, but for the sake of simplicity, not all the details are described in the doc.

There's actually a slight difference when the cache is set tobuild_dir orcache_dir (other than the directory itself).
Ifbuild_dir is used, we construct a two layers cache with a read-only layer pointing tobuild_dir and a read/write opportunistic cache pointing tocache_dir.
Ifcache_dir is used, we set up a simple one-layer cache oncache_dir.

Hence why the distinction, even if you are actually right with the simplified version.

Happy to discuss any improvements we can make on the doc for this 👍

Thanks for the detailed explanation 🙏 I think you are right that it's better to not mention all these internal details in the docs.

Also, let's wait until Symfony usesbuild_dir for everything and it's "fully read-only" to see if we can tweak many docs at once related to that if we think it's needed.