From 3b017bfde0cd71d7ab3843c90f21b38a4b7406bd Mon Sep 17 00:00:00 2001 From: Michael Shepanski Date: Mon, 20 Feb 2017 14:56:46 -0500 Subject: [PATCH] Update docs --- docs/configuration.rst | 131 +++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 76 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 054192d0..419e6206 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,15 +1,10 @@ Configuration ============= - -.. |br| raw:: html - -
- -The default configuration file path is :samp:`~/.config/plexapi/config.ini` -which can be overridden by setting the environment variable -:samp:`PLEXAPI_CONFIG_PATH` with the filepath you desire. All configuration -variables in this file are optional. An example config.ini file may look like -the following with all possible value specified. +Python-PlexAPI will work fine without any configuration. However, sometimes there are things you +may wish to alter for more control of the default behavior. The default configuration file path +is :samp:`~/.config/plexapi/config.ini` which can be overridden by setting the environment variable +:samp:`PLEXAPI_CONFIG_PATH` with the filepath you desire. All configuration variables in this file +are optional. An example config.ini file may look like the following with all possible value specified. .. code-block:: ini @@ -42,104 +37,89 @@ the following with all possible value specified. Environment Variables --------------------- -All configuration values can be set or overridden via environment variables. The -environment variable names are in all upper case and follow the format -:samp:`PLEXAPI_
_`. For example, if you wish to set the log path via an -environment variable, you may specify: `PLEXAPI_LOG_PATH="/tmp/plexapi.log"` +All configuration values can be set or overridden via environment variables. The environment variable +names are in all upper case and follow the format :samp:`PLEXAPI_
_`. For example, if +you wish to set the log path via an environment variable, you may specify: `PLEXAPI_LOG_PATH="/tmp/plexapi.log"` Section [plexapi] Options ------------------------- **container_size** - Default max results to return in on single search page. Looping through - result pages is done internall by the API. Therfore, tuning this setting - will not affect usage of plexapi. However, it help improve performance for - large media collections (default: 50). + Default max results to return in on single search page. Looping through result pages is done + internall by the API. Therfore, tuning this setting will not affect usage of plexapi. However, + it help improve performance for large media collections (default: 50). **timeout** - Timeout in seconds to use when making requests to the Plex Media Server - or Plex Client resources (default: 30). + Timeout in seconds to use when making requests to the Plex Media Server or Plex Client + resources (default: 30). Section [auth] Options ---------------------- **myplex_username** - Default MyPlex (plex.tv) username to use when creating a new - :any:`MyPlexAccount` object. Specifying this along with :samp:`auth.myplex_password` - allow you to more easily connect to your account and remove the need to hard - code the username and password in any supplemental scripts you may write. To - create an account object using these values you may simply specify - :samp:`account = MyPlexAccount()` without any arguments (default: None). + Default MyPlex (plex.tv) username to use when creating a new :any:`MyPlexAccount` object. Specifying + this along with :samp:`auth.myplex_password` allow you to more easily connect to your account and + remove the need to hard code the username and password in any supplemental scripts you may write. To + create an account object using these values you may simply specify :samp:`account = MyPlexAccount()` + without any arguments (default: None). **myplex_password** - Default MyPlex (plex.tv) password to use when creating a new :any:`MyPlexAccount` - object. See `auth.myplex_password` for more information and example usage - (default: None). + Default MyPlex (plex.tv) password to use when creating a new :any:`MyPlexAccount` object. See + `auth.myplex_password` for more information and example usage (default: None). - WARNING: When specifying a password or token in the configuration file, be - sure lock it down (persmission 600) to ensure no other users on the system - can read them. Or better yet, only specify sensitive values as a local - environment variables. + WARNING: When specifying a password or token in the configuration file, be sure lock it down + (persmission 600) to ensure no other users on the system can read them. Or better yet, only specify + sensitive values as a local environment variables. **server_baseurl** - Default baseurl to use when creating a new :any:`PlexServer` object. - Specifying this along with :samp:`auth.server_token` allow you to more easily - connect to a server and remove the need to hard code the baseurl and token - in any supplemental scripts you may write. To create a server object using - these values you may simply specify :samp:`plex = PlexServer()` without any - arguments (default: None). + Default baseurl to use when creating a new :any:`PlexServer` object. Specifying this along with + :samp:`auth.server_token` allow you to more easily connect to a server and remove the need to hard + code the baseurl and token in any supplemental scripts you may write. To create a server object using + these values you may simply specify :samp:`plex = PlexServer()` without any arguments (default: None). **server_token** - Default token to use when creating a new :any:`PlexServer` object. - See `auth.server_baseurl` for more information and example usage (default: - None). + Default token to use when creating a new :any:`PlexServer` object. See `auth.server_baseurl` for more + information and example usage (default: None). - WARNING: When specifying a password or token in the configuration file, be - sure lock it down (persmission 600) to ensure no other users on the system - can read them. Or better yet, only specify sensitive values as a local - environment variables. + WARNING: When specifying a password or token in the configuration file, be sure lock it down + (persmission 600) to ensure no other users on the system can read them. Or better yet, only specify + sensitive values as a local environment variables. Section [header] Options ------------------------ **device** - Header value used for X_PLEX_DEVICE to all Plex server and Plex client - requests. Example devices include: iPhone, FireTV, Linux (default: - `result of platform.uname()[0]`). + Header value used for X_PLEX_DEVICE to all Plex server and Plex client requests. Example devices + include: iPhone, FireTV, Linux (default: `result of platform.uname()[0]`). **device_name** - Header value used for X_PLEX_DEVICE_NAME to all Plex server and Plex client - requests. Example device names include: hostname or phone name - (default: `result of platform.uname()[1]`). + Header value used for X_PLEX_DEVICE_NAME to all Plex server and Plex client requests. Example device + names include: hostname or phone name (default: `result of platform.uname()[1]`). **identifier** - Header value used for X_PLEX_IDENTIFIER to all Plex server and Plex client - requests. This is generally a UUID, serial number, or other number unique - id for the device (default: `result of hex(uuid.getnode())`). + Header value used for X_PLEX_IDENTIFIER to all Plex server and Plex client requests. This is generally + a UUID, serial number, or other number unique id for the device (default: `result of hex(uuid.getnode())`). **platorm** - Header value used for X_PLEX_PLATFORM to all Plex server and Plex client - requests. Example platforms include: iOS, MacOSX, Android, LG (default: - `result of platform.uname()[0]`). + Header value used for X_PLEX_PLATFORM to all Plex server and Plex client requests. Example platforms + include: iOS, MacOSX, Android, LG (default: `result of platform.uname()[0]`). **platform_version** - Header value used for X_PLEX_PLATFORM_VERSION to all Plex server - and Plex client requests. This is genrally the server or client operating - system version: 4.3.1, 10.6.7, 3.2 (default: `result of platform.uname()[2]`). + Header value used for X_PLEX_PLATFORM_VERSION to all Plex server and Plex client requests. This is + genrally the server or client operating system version: 4.3.1, 10.6.7, 3.2 (default: `result of + platform.uname()[2]`). **product** - Header value used for X_PLEX_PRODUCT to all Plex server and Plex client - requests. This is the Plex application name: Laika, Plex Media Server, - Media Link (default: PlexAPI). + Header value used for X_PLEX_PRODUCT to all Plex server and Plex client requests. This is the Plex + application name: Laika, Plex Media Server, Media Link (default: PlexAPI). **provides** - Header value used for X_PLEX_PROVIDES to all Plex server and Plex client - requests This is generally one or more of: controller, player, server - (default: PlexAPI). + Header value used for X_PLEX_PROVIDES to all Plex server and Plex client requests This is generally one + or more of: controller, player, server (default: PlexAPI). **version** - Header value used for X_PLEX_VERSION to all Plex server and Plex client - requests. This is the Plex application version (default: plexapi.VERSION). + Header value used for X_PLEX_VERSION to all Plex server and Plex client requests. This is the Plex + application version (default: plexapi.VERSION). Section [log] Options @@ -156,14 +136,13 @@ Section [log] Options Log level to use when for plexapi logging (default: INFO). **path** - Filepath to save plexapi logs to. If not specified, plexapi will not save - logs to an output file (default: None). + Filepath to save plexapi logs to. If not specified, plexapi will not save logs to an output + file (default: None). **rotate_bytes** - Max size of the log file before rotating logs to a backup file - (default: 512000 equals 0.5MB). + Max size of the log file before rotating logs to a backup file (default: 512000 equals 0.5MB). **secrets** - By default Plex will hide all passwords and token values when logging. Set - this to 'true' to enable logging these secrets. This should only be done on - a private server and only enabled when needed (default: false). + By default Plex will hide all passwords and token values when logging. Set this to 'true' to enable + logging these secrets. This should only be done on a private server and only enabled when needed + (default: false).