Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

#3751 document -M command line option #3938

Merged
merged 3 commits into from
Sep 24, 2017
Merged

#3751 document -M command line option #3938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
68fe4b2
#3751 document -M command line option
TimKam Jul 16, 2017
6413833
#3751 work in feedback
TimKam Aug 1, 2017
ec9f373
#3751 use double back ticks
TimKam Aug 22, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
26 changes: 26 additions & 0 deletions doc/man/sphinx-build.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,30 @@ Options
See :ref:`builders` for a list of all builders shipped with Sphinx.
Extensions can add their own builders.

.. _make_mode:

.. option:: -M buildername
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module,
which provides the same build functionality as a default :ref:`Makefile or
Make.bat <makefile_options>`. In addition to all Sphinx
:ref:`builders <builders>`, the following build pipelines are available:

**latexpdf**
Build LaTeX files and run them through :program:`pdflatex`.

**latexpdfja**
Build LaTeX files and run them through :program:`platex/dvipdfmx`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now we recommend to use latexpdf instead.

We recommend using ``latexpdf`` instead.

**info**
Build Texinfo files and run them through :program:`makeinfo`.

.. important::
Sphinx only recognizes the ``-M`` option if it is placed first.

.. versionadded:: 1.2.1

.. option:: -a

If given, always write all output files. The default is to only write output
Expand Down Expand Up @@ -235,6 +259,8 @@ The :program:`sphinx-build` refers following environment variables:
A path to make command. A command name is also allowed.
:program:`sphinx-build` uses it to invoke sub-build process on make-mode.

.. _makefile_options:

.. rubric:: Makefile Options

The :file:`Makefile` and :file:`make.bat` files created by
Expand Down
3 changes: 2 additions & 1 deletion doc/man/sphinx-quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,8 @@ Options

.. option:: --use-make-mode, --no-use-make-mode

Makefile/make.bat uses (or not use) make-mode. Default is use.
:file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode <make_mode>`.
Default is ``use``, which generates a more concise :file:`Makefile/make.bat`.

.. versionchanged:: 1.5
make-mode is default.
Expand Down