From 716af1b9663a10e69235b81e997c5e2560aa44b9 Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Thu, 21 Jun 2018 14:55:31 +0100 Subject: [PATCH] doc: Make config listsing a consistent style --- .../developer_reference/writing_plugins.rst | 14 ++-- .../user_information/how_tos/agenda.rst | 67 ++++++++----------- .../user_information/how_tos/device_setup.rst | 40 +++-------- .../user_reference/configuration.rst | 25 +++---- 4 files changed, 57 insertions(+), 89 deletions(-) diff --git a/doc/source/developer_information/developer_reference/writing_plugins.rst b/doc/source/developer_information/developer_reference/writing_plugins.rst index 27e0457b..2d980b4d 100644 --- a/doc/source/developer_information/developer_reference/writing_plugins.rst +++ b/doc/source/developer_information/developer_reference/writing_plugins.rst @@ -479,12 +479,12 @@ All plugins can be parametrized. Parameters are specified using :class:`wa.framework.plugin.Parameter` instances. The following attributes can be specified on parameter creation: -name +:name: This is the only mandatory argument. The name will be used to create a corresponding attribute in the plugin instance, so it must be a valid Python identifier. -kind +:kind: This is the type of the value of the parameter. This must be an callable. Normally this should be a standard Python type, e.g. ``int`` or ``float``, or one the types defined in :mod:`wa.utils.types`. @@ -494,7 +494,7 @@ kind valid value for a parameter. If you don't want to allow ``None``, then set ``mandatory`` (see below) to ``True``. -allowed_values +:allowed_values: A list of the only allowed values for this parameter. .. note:: For composite types, such as ``list_of_strings`` or @@ -502,11 +502,11 @@ allowed_values the value will be checked against ``allowed_values`` rather than the composite value itself. -default +:default: The default value to be used for this parameter if one has not been specified by the user. Defaults to ``None``. -mandatory +:mandatory: A ``bool`` indicating whether this parameter is mandatory. Setting this to ``True`` will make ``None`` an illegal value for the parameter. Defaults to ``False``. @@ -521,13 +521,13 @@ mandatory (e.g. something like login credentials), should you consider making it mandatory. -constraint +:constraint: This is an additional constraint to be enforced on the parameter beyond its type or fixed allowed values set. This should be a predicate (a function that takes a single argument -- the user-supplied value -- and returns a ``bool`` indicating whether the constraint has been satisfied). -override +:override: A parameter name must be unique not only within an plugin but also with that plugin's class hierarchy. If you try to declare a parameter with the same name as already exists, you will get an error. If you do diff --git a/doc/source/user_information/how_tos/agenda.rst b/doc/source/user_information/how_tos/agenda.rst index a206b0a9..da05fcbe 100644 --- a/doc/source/user_information/how_tos/agenda.rst +++ b/doc/source/user_information/how_tos/agenda.rst @@ -237,52 +237,43 @@ All ApkWorkloads have parameters that affect the way in which APK files are resolved, ``exact_abi``, ``force_install`` and ``prefer_host_package``. Their exact behaviours are outlined below. -.. confval:: exact_abi +:exact_abi: If this setting is enabled WA's resource resolvers will look for the + devices ABI with any native code present in the apk. By default this setting + is disabled since most apks will work across all devices. You may wish to + enable this feature when working with devices that support multiple ABI's + (like 64-bit devices that can run 32-bit APK files) and are specifically + trying to test one or the other. - If this setting is enabled WA's resource resolvers will look for the devices - ABI with any native code present in the apk. By default this setting is - disabled since most apks will work across all devices. You may wish to enable - this feature when working with devices that support multiple ABI's (like - 64-bit devices that can run 32-bit APK files) and are specifically trying to - test one or the other. +:force_install: If this setting is enabled WA will *always* use the APK file on + the host, and re-install it on every iteration. If there is no APK on the + host that is a suitable version and/or ABI for the workload WA will error + when ``force_install`` is enabled. -.. confval:: force_install +:prefer_host_package: This parameter is used to specify a preference over host + or target versions of the app. When set to ``True`` WA will prefer the host + side version of the APK. It will check if the host has the APK and whether it + meets the version requirements of the workload. If so, and the target also + already has same version nothing will be done, otherwise WA will overwrite + the targets installed application with the host version. If the host is + missing the APK or it does not meet version requirements WA will fall back to + the app on the target if present and is a suitable version. When this + parameter is set to ``False`` WA will prefer to use the version already on + the target if it meets the workloads version requirements. If it does not it + will fall back to searching the host for the correct version. In both modes + if neither the host nor target have a suitable version, WA will produce and + error and will not run the workload. - If this setting is enabled WA will *always* use the APK file on the host, and - re-install it on every iteration. If there is no APK on the host that is a - suitable version and/or ABI for the workload WA will error when - ``force_install`` is enabled. - -.. confval:: prefer_host_package - - This parameter is used to specify a preference over host or target versions - of the app. When set to ``True`` WA will prefer the host side version of the - APK. It will check if the host has the APK and whether it meets the version - requirements of the workload. If so, and the target also already has same - version nothing will be done, otherwise WA will overwrite the targets - installed application with the host version. If the host is missing the APK - or it does not meet version requirements WA will fall back to the app on the - target if present and is a suitable version. When this parameter is set to - ``False`` WA will prefer to use the version already on the target if it meets - the workloads version requirements. If it does not it will fall back to - searching the host for the correct version. In both modes if neither the host - nor target have a suitable version, WA will produce and error and will not - run the workload. - -.. confval:: version - - This parameter is used to specify which version of uiautomation for the - workload is used. In some workloads e.g. ``geekbench`` multiple versions with - drastically different UI's are supported. A APKs version will be +:version: This parameter is used to specify which version of uiautomation for + the workload is used. In some workloads e.g. ``geekbench`` multiple versions + with drastically different UI's are supported. A APKs version will be automatically extracted therefore it is possible to have multiple apks for different versions of a workload present on the host and select between which is used for a particular job by specifying the relevant version in your :ref:`agenda `. -.. confval:: variant_name - - Some workloads use variants of APK files, this is usually the case with web - browser APK files, these work in exactly the same way as the version. +:variant_name: Some workloads use variants of APK files, this is usually the + case with web browser APK files, these work in exactly the same way as the + version. IDs and Labels diff --git a/doc/source/user_information/how_tos/device_setup.rst b/doc/source/user_information/how_tos/device_setup.rst index d8a1ca7a..697daeb6 100644 --- a/doc/source/user_information/how_tos/device_setup.rst +++ b/doc/source/user_information/how_tos/device_setup.rst @@ -34,24 +34,18 @@ The device interface may be configured through ``device_config`` setting, who's value is a ``dict`` mapping setting names to their values. Some of the most common parameters you might want to change are outlined below. -.. confval:: device - - If you have multiple Android devices connected to the host machine, you will +:device: If you have multiple Android devices connected to the host machine, you will need to set this to indicate to WA which device you want it to use. The will be the adb name the is displayed when running ``adb devices`` -.. confval:: working_directory - - WA needs a "working" directory on the device which it will use for collecting +:working_directory: WA needs a "working" directory on the device which it will use for collecting traces, caching assets it pushes to the device, etc. By default, it will create one under ``/sdcard`` which should be mapped and writable on standard Android builds. If this is not the case for your device, you will need to specify an alternative working directory (e.g. under ``/data/local``). -.. confval:: modules - - A list of additional modules to be installed for the target. Devlib +:modules: A list of additional modules to be installed for the target. Devlib implements functionality for particular subsystems as modules. A number of "default" modules (e.g. for cpufreq subsystem) are loaded automatically, unless explicitly disabled. If additional modules need to be loaded, they @@ -62,9 +56,7 @@ common parameters you might want to change are outlined below. .. _core-names: -.. confval:: core_names - - ``core_names`` should be a list of core names matching the order in which +:core_names: ``core_names`` should be a list of core names matching the order in which they are exposed in sysfs. For example, Arm TC2 SoC is a 2x3 big.LITTLE system; its core_names would be ``['a7', 'a7', 'a7', 'a15', 'a15']``, indicating that cpu0-cpu2 in cpufreq sysfs structure are A7's and cpu3 and @@ -187,31 +179,21 @@ value is a ``dict`` mapping setting names to their values. Some of the most common parameters you might want to change are outlined below. -.. confval:: host +:host: This should be either the the DNS name or IP address of the device. - This should be either the the DNS name or IP address of the device. - -.. confval:: username - - The login name of the user on the device that WA will use. This user should +:username: The login name of the user on the device that WA will use. This user should have a home directory (unless an alternative working directory is specified using ``working_directory`` config -- see below), and, for full functionality, the user should have sudo rights (WA will be able to use sudo-less acounts but some instruments or workload may not work). -.. confval:: password - - Password for the account on the device. Either this of a ``keyfile`` (see +:password: Password for the account on the device. Either this of a ``keyfile`` (see below) must be specified. -.. confval:: keyfile - - If key-based authentication is used, this may be used to specify the SSH identity +:keyfile: If key-based authentication is used, this may be used to specify the SSH identity file instead of the password. -.. confval:: property_files - - This is a list of paths that will be pulled for each WA run into the __meta +:property_files: This is a list of paths that will be pulled for each WA run into the __meta subdirectory in the results. The intention is to collect meta-data about the device that may aid in reporducing the results later. The paths specified do not have to exist on the device (they will be ignored if they do not). The @@ -261,9 +243,7 @@ subset of functionality can be performed. In order to distinguish between the two connections some of the android specific configuration has been renamed to reflect the destination. -.. confval:: android_working_directory - - WA needs a "working" directory on the device which it will use for collecting +:android_working_directory: WA needs a "working" directory on the device which it will use for collecting traces, caching assets it pushes to the device, etc. By default, it will create one under ``/sdcard`` which should be mapped and writable on standard Android builds. If this is not the case for your device, you will need to diff --git a/doc/source/user_information/user_reference/configuration.rst b/doc/source/user_information/user_reference/configuration.rst index 9fb6e72c..525d8ffb 100644 --- a/doc/source/user_information/user_reference/configuration.rst +++ b/doc/source/user_information/user_reference/configuration.rst @@ -53,24 +53,21 @@ In addition to standard configuration described above, WA behaviour can be altered through environment variables. These can determine where WA looks for various assets when it starts. -.. confval:: WA_USER_DIRECTORY - - This is the location WA will look for config.yaml, plugins, dependencies, - and it will also be used for local caches, etc. If this variable is not set, - the default location is ``~/.workload_automation`` (this is created when WA - is installed). +:WA_USER_DIRECTORY: This is the location WA will look for config.yaml, plugins, + dependencies, and it will also be used for local caches, etc. If this + variable is not set, the default location is ``~/.workload_automation`` (this + is created when WA is installed). .. note:: This location **must** be writable by the user who runs WA. -.. confval:: WA_LOG_BUFFER_CAPACITY - - Specifies the capacity (in log records) for the early log handler which is - used to buffer log records until a log file becomes available. If the is not - set, the default value of ``1000`` will be used. This should sufficient for - most scenarios, however this may need to be increased, e.g. if plugin loader - scans a very large number of locations; this may also be set to a lower - value to reduce WA's memory footprint on memory-constrained hosts. +:WA_LOG_BUFFER_CAPACITY: Specifies the capacity (in log records) for the early + log handler which is used to buffer log records until a log file becomes + available. If the is not set, the default value of ``1000`` will be used. + This should sufficient for most scenarios, however this may need to be + increased, e.g. if plugin loader scans a very large number of locations; + this may also be set to a lower value to reduce WA's memory footprint on + memory-constrained hosts. ---------------------