From e40edfed6e08966c722e03c053214097009ccbde Mon Sep 17 00:00:00 2001 From: Jonatan Heyman Date: Fri, 1 May 2020 16:27:58 +0200 Subject: [PATCH] Add config file keys to settings table in the Configuration docs. Remove advanced configuration examples from Quickstart docs in favor of just linking to the Configuration docs. --- .gitignore | 2 +- docs/conf.py | 7 +++--- docs/configuration.rst | 56 ++++++++++++++++++++++++++---------------- docs/quickstart.rst | 18 ++------------ 4 files changed, 42 insertions(+), 41 deletions(-) diff --git a/.gitignore b/.gitignore index 4c1cd62663..e8db7f32c3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ locust.egg-info/** locustio.egg-info/** docs/_build/** docs/cli-help-output.txt -docs/env-options.rst +docs/config-options.rst mock.*.egg dist/** .idea/** diff --git a/docs/conf.py b/docs/conf.py index 38dab32863..ea66ccbb31 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,7 +26,7 @@ def save_locust_help_output(): # Generate RST table with help/descriptions for all available environment variables def save_locust_env_variables(): - env_options_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "env-options.rst") + env_options_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "config-options.rst") print("Generating RST table for Locust environment variables and storing in %s" % env_options_output_file) parser = get_empty_argument_parser() setup_parser_arguments(parser) @@ -34,8 +34,9 @@ def save_locust_env_variables(): for action in parser._actions: if action.env_var: table_data.append(( - action.env_var, ", ".join(["``%s``" % c for c in action.option_strings]), + "``%s``" % action.env_var, + ", ".join(["``%s``" % c for c in parser.get_possible_config_keys(action) if not c.startswith("--")]), action.help, )) colsizes = [max(len(r[i]) for r in table_data) for i in range(len(table_data[0]))] @@ -43,7 +44,7 @@ def save_locust_env_variables(): rows = [formatter.format(*row) for row in table_data] edge = formatter.format(*['=' * c for c in colsizes]) divider = formatter.format(*['-' * c for c in colsizes]) - headline = formatter.format(*["Name", "Command line option", "Description"]) + headline = formatter.format(*["Command line", "Environment", "Config file", "Description"]) output = "\n".join([ edge, headline, diff --git a/docs/configuration.rst b/docs/configuration.rst index a7f95a6c9d..be632443cb 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -7,7 +7,7 @@ Configuration Command Line Options ----------------------------- -The most straight forward way to Configure how Locust is run is through command line options. +The most straight forward way to Configure how Locust is run is through command line arguments. .. code-block:: console @@ -20,40 +20,54 @@ The most straight forward way to Configure how Locust is run is through command .. _environment-variables: -Environment variables +Environment Variables --------------------- -Most of the configuration that can be set through command line arguments can also be set through -environment variables. Here's a table of all the available environment variables: +Most of the options that can be set through command line arguments can also be set through +environment variables. Example: -.. include:: env-options.rst +.. code-block:: + $ LOCUST_LOCUSTFILE=custom_locustfile.py locust -.. _configuration-files: +.. _configuration-file: -Configuration files -------------------- +Configuration File +------------------ -Any of the configuration that can be set through command line arguments can also be set by a +Any of the options that can be set through command line arguments can also be set by a configuration file in the `config file `_ -format. +format. + Locust will look for ``locust.conf`` or ``~/.locust.conf`` by default, or a file may be specified -with the ``--config`` flag. Parameters passed as command line arguments will override the settings -from the config file. +with the ``--config`` flag. Parameters passed as environment variables will override the settings +from the config file, and command line arguments will override the settings from both environment +variables and config file. +Example: .. code-block:: - # step_mode.conf in current directory - locustfile locust_files/my_locust_file.py - host localhost - users 100 - hatch-rate 10 - step-load - step-users 20 - step-time 60 + # master.conf in current directory + locustfile = locust_files/my_locust_file.py + headless = true + master = true + expect-workers = 5 + host = http://target-system + users = 100 + hatch-rate = 10 + run-time = 10m + .. code-block:: console - $ locust --config=step_mode.conf + $ locust --config=master.conf + + +All available configuration options +----------------------------------- + +Here's a table of all the available configuration options, and their corresponding Environment and config file keys: + +.. include:: config-options.rst diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 26cc225d53..4aba5e096a 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -144,22 +144,8 @@ host defaults to 127.0.0.1): $ locust -f locust_files/my_locust_file.py --worker --master-host=192.168.0.100 -Parameters can also be set as :ref:`environment variables `, or in a -`config file `_. -Locust will look for ``locust.conf`` or ``~/.locust.conf`` by default, or a file may be specified -with the ``--config`` flag. - -For example: (this will do the same thing as the previous command) - -.. code-block:: console - - $ LOCUST_MASTER_NODE_HOST=192.168.0.100 locust - -.. code-block:: - - # locust.conf in current directory - locustfile locust_files/my_locust_file.py - worker +Parameters can also be set through :ref:`environment variables `, or in a +:ref:`config file `. .. note::