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

43 views
Skip to first unread message

Nirmal Sasidharan

unread,
Apr 23, 2022, 6:37:39 AMApr 23
to sphinx-users
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

unread,
May 5, 2022, 1:16:33 PMMay 5
to sphinx-users
Reply all
Reply to author
Forward
0 new messages