From 38d2df7705ec9ba0e463337cd13d331c6aa3dcba Mon Sep 17 00:00:00 2001 From: Tom Keffer Date: Sun, 16 Jul 2023 15:57:54 -0700 Subject: [PATCH] More details on `weectl station upgrade` --- bin/weecfg/station_config.py | 2 +- bin/weectllib/station_cmd.py | 6 +-- docs_src/utilities/weectl-station.md | 67 ++++++++++++++++++---------- 3 files changed, 48 insertions(+), 27 deletions(-) diff --git a/bin/weecfg/station_config.py b/bin/weecfg/station_config.py index 32f2b516..2f3e35bc 100644 --- a/bin/weecfg/station_config.py +++ b/bin/weecfg/station_config.py @@ -705,7 +705,7 @@ def station_upgrade(config_path, dist_config_path=None, docs_root=None, examples 'docs': 'documentation', 'util': 'utility files'} choices = ', '.join([abbrev.get(p, p) for p in what]) - msg = f"\nUpgrade {choices} at {config_path}? (Y/n) " + msg = f"\nUpgrade {choices} in {config_dict['WEEWX_ROOT']}? (Y/n) " ans = weeutil.weeutil.y_or_n(msg, noprompt=no_prompt, default='y') diff --git a/bin/weectllib/station_cmd.py b/bin/weectllib/station_cmd.py index e2c8accb..16e6026f 100644 --- a/bin/weectllib/station_cmd.py +++ b/bin/weectllib/station_cmd.py @@ -66,7 +66,7 @@ CREATE_DESCRIPTION = """Create a new user data area, including a configuration f + WEEWX_ROOT_DESCRIPTION UPGRADE_DESCRIPTION = """Upgrade an existing user data area, including any combination of the -configuration file, docs, examples, daemon utility files, and skins. """ + WEEWX_ROOT_DESCRIPTION +configuration file, docs, examples, utility files, and skins. """ + WEEWX_ROOT_DESCRIPTION def add_subparser(subparsers): @@ -143,7 +143,7 @@ def add_subparser(subparsers): usage=station_upgrade_usage, description=UPGRADE_DESCRIPTION, help='Upgrade any combination of the configuration file, docs, ' - 'examples, daemon utility files, and skins.') + 'examples, utility files, and skins.') station_upgrade_parser.add_argument('--docs-root', help='Where to put the new documentation, relative to ' @@ -160,7 +160,7 @@ def add_subparser(subparsers): nargs='+', help='What to upgrade. Default is to upgrade the ' 'configuration file, documentation, examples, and ' - 'daemon utility files.') + 'utility files.') station_upgrade_parser.add_argument('--no-backup', action='store_true', help='Do not backup the old configuration file.') station_upgrade_parser.add_argument('--no-prompt', action='store_true', diff --git a/docs_src/utilities/weectl-station.md b/docs_src/utilities/weectl-station.md index 71368ebb..2a229641 100644 --- a/docs_src/utilities/weectl-station.md +++ b/docs_src/utilities/weectl-station.md @@ -3,11 +3,10 @@ Use the `weectl` subcommand `station` to manage the user data for a station, including its configuration file. -Specify `--help` to see the actions and options. +Specify `--help` to see the actions and options. -In the documentation that follows, the exact output will depend on your -operating system and username. What is shown below is for Linux and user -`tkeffer`. +See the section [_Options used by `weectl station`_](#options) below for details of the various +options. ## Create a new user data area @@ -60,8 +59,6 @@ example, will create a station with the indicated values. If a value is not specified, a default will be used. -See the section [_Common options_](#common-options) for details of the various options. - ## Reconfigure an existing station weectl station reconfigure @@ -113,29 +110,36 @@ For example, to keep all settings, but change to the Vantage driver you would us [--dry-run] -If you installed using pip, then do an upgrade using pip, it will only upgrade the code base. It -does not touch the user data area. Use this action to upgrade all or part of the user data area. +### Upgrade a pip install -It can also be useful for upgrading a package install. While these generally +If you [upgrade a pip install](/quickstarts/pip/#upgrade), it will only upgrade the code base. It +does not touch the user data area. Use this action to do that. - -### --what - -By default, `weectl station upgrade` will upgrade the configuration file, documentation, examples, -and utility files. However, you can customize exactly what gets upgraded. - -!!! Note - The `--what` option does not take an equal sign (`=`). Just list the - desired things to be upgraded, without commas between them. - -For example, to upgrade the configuration file and skins only, you would -specify +By default, the action will upgrade the configuration file, documentation, examples, and utility files. It +will not upgrade your skins. ``` -weectl station upgrade --what config skins +# Make sure your virtual environment is still active: +source ~/weewx-venv/bin/activate +# Upgrade configuration file, documentation, examples, and utility files: +weectl station upgrade ``` -## Common options {#common-options} +If you wish to upgrade the skins, specify it using the `--what` command: + +``` +weectl station upgrade --what skins +``` + +This will copy in the current version of the skins, leaving timestamped backups of your old skins. + +### Upgrade of package installs + + +TODO + + +## Options used by `weectl station` {#options} In what follows, `WEEWX_ROOT` is the directory holding the configuration file. For a pip install, this is typically `~/weewx-data/`. For package installs, it is usually `/etc/weewx/`. @@ -214,6 +218,23 @@ path, if the option starts with a slash (`/`), it becomes an absolute path. Defa Where the WeeWX examples can be found, *relative to `WEEWX_ROOT`*. Of course, like any other path, if the option starts with a slash (`/`), it becomes an absolute path. Default is `examples`. +### --what + +By default, `weectl station upgrade` will upgrade the configuration file, documentation, examples, +and utility files. However, you can customize exactly what gets upgraded by using the `--what` +option. + +!!! Note + The `--what` option does not take an equal sign (`=`). Just list the + desired things to be upgraded, without commas between them. + +For example, to upgrade the configuration file and skins only, you would +specify + +``` +weectl station upgrade --what config skins +``` + ### --no-backup Generally, if `weectl station` changes your configuration file, it will save a timestamped version