#3751 document -M command line option

[TimKam]

Documents sphinx-build -M command line option

Feature or Bugfix

• Doc

Purpose

Documents sphinx-build -M command line option:
Build using the Sphinx make_mode module.

Detail

Only updates the docs. At #3196 (comment) are some suggestions to improve the command line (help) interface. I might create another PR for this eventually.

Relates

#3751

[tk0miya]

Now we recommend to use latexpdf instead.

[tk0miya]

Sphinx only recognize -M option only if it is placed at first.

$ sphinx-build -v -M html . _build/html
Sphinx v1.7+
Usage: sphinx-build [options] sourcedir outdir [filenames...]

Filename arguments:
  without -a and without filenames, write new and changed files.
  with -a, write all files.
  with filenames, write these.

sphinx-build: error: no such option: -M

[peterjc]

This prevents doing things like this:

make SPHINXBUILD="python -msphinx -W" -C Doc/api/ html

in place of just:

make -C Doc/api/ html

in order to add extra arguments to sphinx-build (here -W for a strict run).

This worked on older versions of Sphinx as the Makefile did not use the -M argument.

[peterjc]

Solved my own issue, the new Makefile design lets me use SPHINXOPTS = -W which is a cleaner solution.

[jfbu]

@peterjc you can use O shortcut, make -C Doc/api/ html O="-W"

[TimKam]

Thanks for the feedback. I worked in your comments.

[tk0miya]

Please use literal notation (double-backquote) for use.

[tk0miya]

Thanks!