sphinx-build, as per the documentation, supports two options to use
builders.
-b
<https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-b>
and -M
<https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-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
<https://www.sphinx-doc.org/en/master/man/sphinx-quickstart.html>, creates
a Makefile with "-M", but the getting-started
<https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build>
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
<https://github.com/swyddfa/esbonio/issues/373> 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.
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/0af0e51a-ea9e-4aa3-842b-d0813a46232fn%40googlegroups.com.
