Commit 7a5ee4aa authored by Jim Fulton's avatar Jim Fulton Committed by GitHub

Added reference documentation for command-line options (#354)

* Added reference documentation for command-line options

- Intentionally didn't document -o, -O and -n

  Offline mode is an attractive nuisance.

  -n is unlikely to be needed and can be spelled newest=true

- Removed -o, -O and -n from command help.

- Sorted options alphabetically in the reference doc and command help.

- Removed documentation of the log-level option.  It just confuses things.
  I seriously doubt that anyone uses it.
parent 1b94efc6
......@@ -11,35 +11,95 @@ A Buildout execution is of the form:
.. code-block:: console
buildout [buildout-options] [settings] [subcommand [subcommand-arguments]]
buildout [buildout-options] [assignments] [command [command arguments]]
Settings take the form ``section:option=value`` and override (or
augment) settings in configuration files. For example, to pin a
Assignments take the form ``section:option=value`` and override (or
augment) options in configuration files. For example, to pin a
version of ZEO you could use ``versions:ZEO=4.3.1``. The section
defaults to the ``buildout`` section. So, for example: ``parts=test``
sets the ``buildout`` section ``parts`` option.
Command-line settings overrides can use ``+=`` and ``-=`` to
Command-line assignments can use ``+=`` and ``-=`` to
:ref:`merge values with existing values <merge-values-with-existing-values>`
Buildout options
----------------
Buildout command-line options
-----------------------------
Buildout subcommands
--------------------
.. _-c-option:
.. _bootstrap-subcommand:
``-c config_file``
Specify the path (or URL) to the buildout configuration file to be used.
This defaults to the file named ``buildout.cfg`` in the current
working directory.
``-D``
Debug errors. If an error occurs, then the post-mortem debugger
will be started. This is especially useful for debugging recipe
problems.
``-h``, ``--help``
Print basic usage information and exit.
``-N``
Run in :ref:`non-newest mode <non-newest-mode>`. This is equivalent
to the command-line assignment ``newest=false``.
``-q``
Decrease the level of verbosity. This option can be used multiple
times.
Using a single ``-q`` suppresses normal output, but still shows
warnings and errors.
Doubling the option ``-qq`` (or equivalently ``-q -q``) suppresses
normal output and warnings.
Using the option more than twice suppresses errors, which is a bad idea.
``-t socket_timeout``
Specify the socket timeout in seconds. See the
:ref:`socket-timeout option <socket-timeout-option>` for details.
``-U``
Don't use :ref:`user-default configuration <user-default-configuration>`.
``-v``
Increase the level of verbosity. This option can be used multiple
times.
At the default verbosity, buildout prints messages about significant
activities. It also prints warning and error messages.
At the next, "verbose", level (``-v``), it prints much
more information. In particular, buildout will show when and why
it's installing specific distribution versions.
At the next, "debugging", level, ``-vv`` (or equivalently ``-v
-v``), buildout prints low-level debugging information, including a
listing of all configuration options, including: default options,
computed options and the results of :ref:`value substitutions
<value-substitutions>` and :ref:`macros <macros-label>`.
Using this option more than twice has no effect.
``--version``
Print buildout version number and exit.
Buildout commands
-----------------
.. _bootstrap-command:
bootstrap
_________
Install a local ``bootstrap`` script. The ``bootstrap`` subcommand
Install a local ``bootstrap`` script. The ``bootstrap`` command
doesn't take any arguments.
See :doc:`Bootstrapping <topics/bootstrapping>` for information on why
you might want to do this.
.. _init-subcommand:
.. _init-command:
init [requirements]
____________________
......@@ -248,16 +308,6 @@ log-format, default: ''
If ``log-format`` is non-blank, then it will be used for the root logger
[#root-logger]_ (and for Buildout's messages).
log-level, default: 'INFO'
The `logging level
<https://docs.python.org/3/library/logging.html#logging-levels>`_.
This may be adjusted with the :ref:`-v option <-v-option>` or the
:ref:`-q option <-q-option>`, which are the more common ways to control
the logging level.
The ``log-level`` option is rarely used.
.. _newest-mode:
.. _non-newest-mode:
......@@ -276,11 +326,13 @@ offline, default: 'false'
.. Warning:: Offline mode is deprecated.
Its purpose has evolved over time and the end result doesn't
make much sense, but it is retained for backward compatibility.
Its purpose has evolved over time and the end result doesn't make
much sense, but it is retained (indefinitely) for backward
compatibility.
If you think you want an offline mode, you probably want the
:ref:`install-from-cache <install-from-cache-mode>` mode instead.
If you think you want an offline mode, you probably want either
the :ref:`non-newest mode <non-newest-mode>` or the
:ref:`install-from-cache mode <install-from-cache-mode>` instead.
In offline mode, no network requests should be made. It's the
responsibility of recipes to adhere to this. Recipes that would
......@@ -310,6 +362,8 @@ show-picked-versions, default: 'false'
lines it would write to a versions configuration if the
:ref:`update-versions-file <update-versions-file>` option was used.
.. _socket-timeout-option:
socket-timeout, default: ''
Specify a socket timeout [#socket-timeout]_, in seconds, to use when
downloading distributions and other artifacts. If non-blank, the
......
......@@ -30,10 +30,10 @@ Avoid modifying the python environment.
Unfortunately, doing this requires :ref:`using a bootstrap script
<using-a-bootstrap-script>`.
Local bootstrapping using the ``buildout`` subcommand
=====================================================
Local bootstrapping using the ``bootstrap`` command
===================================================
You can use the :ref:`bootstrap subcommand <bootstrap-subcommand>` of a
You can use the :ref:`bootstrap command <bootstrap-command>` of a
``buildout`` script installed in your Python environment to boostrap
the buildout in the current directory:
......@@ -129,8 +129,8 @@ Bootstrapping requires a ``buildout.cfg``, ``init`` creates one
Normally, when bootstrapping, the local directory must have a
``buildout.cfg`` file.
If you don't have one, you can use the :ref:`init subcommand
<init-subcommand>` instead:
If you don't have one, you can use the :ref:`init command
<init-command>` instead:
.. code-block:: console
......
......@@ -67,8 +67,8 @@ user default values
options from one or more configuration files
These override user defaults and each other, as described below.
option values in the :ref:`buildout command line <buildout-command-line>`
These override configuration-file settings.
option assignments in the :ref:`buildout command line <buildout-command-line>`
These override configuration-file options.
.. _extends_option:
......@@ -345,7 +345,7 @@ original *lines*. This is a bit delicate. In the example above,
we were careful to put the base values on separate lines, in
anticipation of using ``-=``.
Merging values also works with option settings provided via the
Merging values also works with option assignments provided via the
:ref:`buildout command line <buildout-command-line>`. For example, if
you want to temporarily use a :ref:`development version
<python-development-projects>` of another project, you can augment the
......
......@@ -1777,27 +1777,32 @@ Usage: buildout [options] [assignments] [command [command arguments]]
Options:
-h, --help
-c config_file
Print this message and exit.
Specify the path to the buildout configuration file to be used.
This defaults to the file named "buildout.cfg" in the current
working directory.
--version
-D
Print buildout version number and exit.
Debug errors. If an error occurs, then the post-mortem debugger
will be started. This is especially useful for debuging recipe
problems.
-v
-h, --help
Increase the level of verbosity. This option can be used multiple times.
Print this message and exit.
-q
-N
Decrease the level of verbosity. This option can be used multiple times.
Run in non-newest mode. This is equivalent to the assignment
buildout:newest=false. With this setting, buildout will not seek
new distributions if installed distributions satisfy it's
requirements.
-c config_file
-q
Specify the path to the buildout configuration file to be used.
This defaults to the file named "buildout.cfg" in the current
working directory.
Decrease the level of verbosity. This option can be used multiple times.
-t socket_timeout
......@@ -1807,37 +1812,13 @@ Options:
Don't read user defaults.
-o
Run in off-line mode. This is equivalent to the assignment
buildout:offline=true.
-O
Run in non-off-line mode. This is equivalent to the assignment
buildout:offline=false. This is the default buildout mode. The
-O option would normally be used to override a true offline
setting in a configuration file.
-n
Run in newest mode. This is equivalent to the assignment
buildout:newest=true. With this setting, which is the default,
buildout will try to find the newest versions of distributions
available that satisfy its requirements.
-N
-v
Run in non-newest mode. This is equivalent to the assignment
buildout:newest=false. With this setting, buildout will not seek
new distributions if installed distributions satisfy it's
requirements.
Increase the level of verbosity. This option can be used multiple times.
-D
--version
Debug errors. If an error occurs, then the post-mortem debugger
will be started. This is especially useful for debuging recipe
problems.
Print buildout version number and exit.
Assignments are of the form: section:option=value and are used to
provide configuration options that override those given in the
......@@ -1888,7 +1869,6 @@ Commands:
alphabetically. For each section, all key-value pairs are displayed,
sorted alphabetically, along with the origin of the value (file name or
COMPUTED_VALUE, DEFAULT_VALUE, COMMAND_LINE_VALUE).
"""
def _help():
......
......@@ -615,6 +615,12 @@ def test_help():
<BLANKLINE>
Options:
<BLANKLINE>
-c config_file
<BLANKLINE>
Specify the path to the buildout configuration file to be used.
This defaults to the file named "buildout.cfg" in the current
working directory.
...
-h, --help
...
......@@ -625,6 +631,12 @@ def test_help():
<BLANKLINE>
Options:
<BLANKLINE>
-c config_file
<BLANKLINE>
Specify the path to the buildout configuration file to be used.
This defaults to the file named "buildout.cfg" in the current
working directory.
...
-h, --help
...
"""
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment