update doc for multi account/config support (#1232)

Author: AndreyNikiforov

docs/authentication.md

@@ -10,7 +10,7 @@ You can receive an email notification when two-factor authentication expires by
 `--smtp-username` and `--smtp-password` options. Emails will be sent to `--smtp-username` by default,
 or you can send to a different email address with `--notification-email`.
 
-If you want to send notification emails using your Gmail account, and you have enabled two-factor authentication, you will need to generate an App Password at <https://myaccount.google.com/apppasswords>
+If you want to send notification emails using your Gmail account, and you have enabled two-factor authentication, you will need to generate an App Password at <https://myaccount.google.com/apppasswords>.
 
 ## MFA Providers
 
@@ -42,6 +42,7 @@ Advanced Data Protection (ADP) for iCloud accounts is not supported because `icl
 
 Some authentication errors may be resolved by clearing `.pyicloud` subfolder in the user's home directory. [Example](https://github.com/icloud-photos-downloader/icloud_photos_downloader/issues/772#issuecomment-1950963522)
 
+(password-providers)=
 ## Password Providers
 
 ```{versionadded} 1.20.0
@@ -85,3 +86,37 @@ icloud --username jappleseed@apple.com --delete-from-keyring
 ```{note}
 Use `icloud`, not `icloudpd`
 ```
+
+(multiple-accounts-and-configs)=
+## Using Multiple Accounts and Config
+
+`icloudpd` can process iCloud collections for multiple accounts or use multiple configs for one account. This is achived by specifying `--username` parameter multiples times: any options specified after `--username` will be applied to mentioned user only. Parameters specified before first `--username` work as defaults for all other user configs. Global app-wide settings can be specified anywhere.
+
+### Example: using two user accounts
+
+```
+$ icloudpd --use-os-locale --cookie-directory ./cookies --username alice@apple.com --directory ./alice --username bob@apple.com --directory ./bob
+```
+
+Explanation
+
+- `--use-os-locale` is global parameter and can be used anywhere
+- `--cookie-directory` is a default for both users; it is okay to use same folder since session and coockies are stored in files based on user name, so they would not collide
+- `--directory ./alice` is specifying that all photos for Alice will be downloaded into ./alice folder
+- `--directory ./bob` is specifying that all photos for Alice will be downloaded into ./alice folder
+
+### Example: using two configs for one account
+
+```
+$ icloudpd --cookie-directory ./cookies --username alice@apple.com --directory ./photos --skip-videos --username alice@apple.com --directory ./videos --skip-photos --use-os-locale
+```
+
+Explanation
+
+- `--cookie-directory` is a default for both configs
+- `--directory ./photos --skip-videos` is specifying that all photos for Alice will be downloaded into ./photos folder
+- `--directory ./videos --skip-photos` is specifying that all videos for Alice will be downloaded into ./videos folder
+- `--use-os-locale` is global parameter and can be used anywhere
+
+```{versionadded} 1.32.0
+```

docs/naming.md

@@ -2,7 +2,7 @@
 
 Assets on iCloud have names. When downloading assets, `icloudpd` can adjust names.
 
-(folder_structure)=
+(folder-structure)=
 ## Folder Structure
 
 ```{versionchanged} 1.7.0
@@ -18,7 +18,7 @@ Specifying `--folder-structure none` will put all files into one folder.
 
 ### Formatting
 
-`icloudpd` follows [Python string formatting grammar](https://docs.python.org/3/library/string.html#formatstrings) for [`--folder-structure`](folder-structure-parameter) parameter,e.g. `{:%Y}` means the need to take only 4-digit year out of created date. Full list of format codes is [available](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
+`icloudpd` follows [Python string formatting grammar](https://docs.python.org/3/library/string.html#formatstrings) for [`--folder-structure`](folder-structure-parameter) parameter, e.g. `{:%Y}` extracts only the 4-digit year from the creation date. Full list of format codes is [available](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
 
 Default format is: `{:%Y/%m/%d}`
 

docs/reference.md

@@ -105,13 +105,13 @@ This is a list of all options available for command line interface (CLI) of the
 :   Specifies iCloud password to use for authentication
 
     ```{note}
-    Supplying credentials through command line parameters is considered not a good practice since they can be logged and/or otherwise exposed. Consider using other [password providers](authentication).
+    Supplying credentials through command line parameters is considered not a good practice since they can be logged and/or otherwise exposed. Consider using other [password providers](password-providers).
     ``` 
 
 (directory-parameter)=
 `--directory X`
 
-:   Specifies root folder where [folder structure](naming) will start and files will be downloaded.
+:   Specifies root folder where [folder structure](folder-structure-parameter) will start and files will be downloaded.
 
 (file-match-policy-parameter)=
 `--file-match-policy X`
@@ -125,7 +125,7 @@ This is a list of all options available for command line interface (CLI) of the
 (username-parameter)=
 `--username X`
 
-:   Specifies AppleID (email address) used for authenticating to iCloud.
+:   Specifies AppleID (email address) used for authenticating to iCloud. May be used multiple times to introduce different configurations and/or accounts. See [Using Multiple Accounts and Config](multiple-accounts-and-configs)
 
 (auth-only-parameter)=
 `--auth-only`
@@ -220,7 +220,7 @@ This is a list of all options available for command line interface (CLI) of the
     ```{seealso}
     [Modes of operation](mode)
 
-    [Folder Structure](folder_structure)
+    [Folder Structure](folder-structure)
     ```
 
 (only-print-filenames-parameter)=
@@ -237,7 +237,7 @@ This is a list of all options available for command line interface (CLI) of the
 :   Specifies sub folder naming scheme. 
 
     ```{seealso}
-    Details in [Folder structure](naming) section.
+    Details in [Folder structure](folder-structure) section.
     ```
 
 (set-exif-datetime-parameter)=
@@ -279,7 +279,7 @@ This is a list of all options available for command line interface (CLI) of the
 :   Customizes intake of the password for iCloud authentication.
 
     ```{seealso}
-    Details in [Password providers](authentication) section.
+    Details in [Password providers](password-providers) section.
     ```
 (mfa-provider-parameter)=
 `--mfa-provider X`

scripts/install_deps

@@ -2,4 +2,4 @@
 # this is used to setup development env (all required dependencies for all cases)
 set -euo pipefail
 python3 -m pip install --disable-pip-version-check -r requirements-pip.txt
-pip3 install --disable-pip-version-check -e . --group test --group dev
+pip3 install --disable-pip-version-check -e . --group test --group dev --group doc