Difference in behavior between -b and -M of sphinx-build

[Nirmal Sasidharan]

sphinx-build, as per the documentation, supports two options to use builders.

-b and -M.

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)

and 

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( 

   ... 

    buildername="html", 

   ... 

 )

Also sphinx-quickstart, creates a Makefile with "-M", but the getting-started documentation talks about using "-b".

This is unfortunately, highly confusing to know which option to use as the best default across tools. See discussion here for example.

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.

[Nirmal Sasidharan]

Created bug here

https://github.com/sphinx-doc/sphinx/issues/10422