sphinx-build, as per the documentation, supports two options to use builders.
Both options seems to behave in slightly different ways.
"-b html" for example, creates pickles in ".doctrees" folder and the output is created directly in the build folder.
"-M html" for example, creates pickles in "doctrees" (without a dot) folder and the output is created under a subfolder "html" in the build folder.
If different sphinx tools trigger builds in the same workspace using "-b" and "-M" it affects,
1. the incremental behavior of sphinx (because of two different doctrees folders)
2. the output is produced twice (once directly under build and another one at build/html)
Sphinx API seems to be have "-M" as the default. Pickles is created in "doctrees" folder.
self.sphinx = sphinx.application.Sphinx(
This is unfortunately, highly confusing to know which option to use as the best default across tools. See discussion here
Firstly, why is this difference in behavior between "-b" and "-M"?
Secondly, what is the best default to ensure compatibility across several sphinx tools depending on the same workspace/build folder?
Thanks in advance for your help.