add cli reference to doc (icloud-photos-downloader#932)

docs/authentication.md

@@ -27,7 +27,7 @@ Default: *console*
 
 ## Access from Mainland China
 
-Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with `--domain cn` parameter to support downloading iCloud photos from mainland China, however, people reported mixed results with that parameter.
+Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with `--domain cn` parameter to support downloading iCloud Photos from mainland China, however, people reported mixed results with that parameter.
 
 ## FIDO
 

docs/conf.py

@@ -28,3 +28,6 @@
 
 html_theme = "furo"
 # html_static_path = ['_static']
+
+# myst config
+myst_enable_extensions = ["deflist"]

docs/index.md

@@ -17,4 +17,5 @@ size
 raw
 webui
 nas
+reference
 ```

docs/mode.md

@@ -6,6 +6,21 @@ Added `--delete-after-download` parameter
 
 `icloudpd` works in one of three modes of operation:
 
-- **Copy** - download new photos from iCloud (default mode)
-- **Sync** - download new photos from iCloud and delete local files that were removed in iCloud (`--auto-delete` parameter)
-- **Move** - download new photos from iCloud and delete photos in iCloud (`--delete-after-download` parameter)
+Copy
+:   Download assets from iCloud that are are not in the local storage
+
+    This is the default mode
+
+Sync
+:   Download assets from iCloud that are are not in the local storage (same as Copy). In addition, delete local files that were removed in iCloud (moved into "Recently Deleted" album)
+
+    This mode is selected with `--auto-delete` parameter
+
+Move
+:   Download assets from iCloud that are are not in the local storage (same as Copy). Then delete assets in iCloud that were just downloaded 
+
+    This mode is selected with `--delete-after-download` parameter
+
+    ```{note}
+    If remote assets were not downloaded, e.g. because they were already in local storage, they will NOT be deleted in iCloud.
+    ```

docs/reference.md

@@ -0,0 +1,258 @@
+# Reference
+
+This is a list of all options available for command line interface (CLI) of the `icloudpd`
+
+(until-found-parameter)=
+`--until-found X`
+
+:   Checks assets, from most recently added to the oldest, for their local copies. 
+    Downloads if not present locally. Whole process stops once X number of subsequent checks result in a local file matching remote.
+
+    This option is a useful optimization for incremental updates: only small portion (X) of the existing local storage will be rechecked for existence, saving on local IO. However, the process will not "fill the gaps" in local storage if any exist (and will not identify them).
+
+    ```{note}
+    Assets are checked by the date they were added to iCloud, not by the date they were taken/created.
+    ```
+
+(recent-parameter)=
+`--recent X`
+
+:   Checks X most recently added assets for their local copies. 
+    Downloads if not present locally. 
+
+    This option is mostly useful while testing and experimenting with parameters to limit the volume of downloads
+
+    ```{note}
+    Assets are checked by the date they were added to iCloud, not by the date they were taken/created.
+    ```
+
+(album-parameter)=
+`--album X`
+
+:   Specifies what Album to download. 
+
+    Default: "All Photos" - Special album where all assets are automatically added.
+
+    ```{note}
+    Only one album can be downloaded by `icloudpd`
+    ```    
+
+(list-albums-parameter)=
+`--list-albums`
+
+:   Lists all available albums 
+
+(library-parameter)=
+`--library X`
+
+:   Specifies what Libarary to use. 
+
+    Default: "Personal Library".
+
+    ```{note}
+    Only one library can be used by `icloudpd`
+    ```    
+
+(list-libraries-parameter)=
+`--list-libraries`
+
+:   Lists all libraries available for account 
+
+(watch-with-interval-parameter)=
+`--watch-with-interval X`
+
+:   Runs `icloudpd` forever, periodically re-checking iCloud for changes ("watch"). Interval is specified in seconds, e.g. 3600 will be 1hr interval.
+
+    Too short interval may trigger throttling on Apple side, although no evidence has been reported.
+
+(version-parameter)=
+`--version`
+
+:   Reports current version and commit hash & date that version was build from.
+
+    ```{note}
+    If `--use-os-locale` was specified before `--version`, then date is formatted according to OS locale.
+    ```    
+
+(use-os-locale-parameter)=
+`--use-os-locale`
+
+:   Instructs `icloudpd` to use OS locale. If not specified (and by default), US English is used.
+
+    ```{seealso}
+    [File Naming](naming) section discusses affected behavior
+    ```    
+
+(dry-run-parameter)=
+`--dry-run`
+
+:   If specified, no changes to local storage or iCloud remote storage is made.
+
+    Authentication will be performed and remote files will be checked against local storage. Any difference will be reported instead of performing download.
+
+    This parameter is useful for experimenting with new parameters
+
+(domain-parameter)=
+`--domain X`
+
+:   Access to Apple servers is blocked from mainland China. As an alternative, iCloud service is available on internal .cn domain, which can be specified for `icloudpd` to work from mainland China.
+
+    Default is ".com". ".cn" is the only other option available.
+
+(password-parameter)=
+`--password X`
+
+:   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).
+    ``` 
+
+(directory-parameter)=
+`--directory X`
+
+:   Specifies root folder where [folder structure](naming) will start and files will be downloaded.
+
+(file-match-policy-parameter)=
+`--file-match-policy X`
+
+:   Specifies an algorithm (policy) to match remote to local files.
+
+    ```{seealso}
+    Discussion on [File Naming and Deduplication](naming)
+    ``` 
+
+(username-parameter)=
+`--username X`
+
+:   Specifies AppleID (email address) used for authenticating to iCloud.
+
+(auth-only-parameter)=
+`--auth-only`
+
+:   Performs authentication, persists auth results (tokens/cookies), and exists without processing assets
+
+(cookie-directory-parameter)=
+`--cookie-directory X`
+
+:   Customizes folder used for persisting authentication results (cookies/tokens). If not specified, `~/.pyicloud` is used.
+
+(size-parameter)=
+`--size X`
+
+:   Customizes size of the asset to download.
+
+    ```{seealso}
+    Details on [Assets sizes](size)
+    ```
+
+(force-size-parameter)=
+`--force-size`
+
+:   If specified, only requested size will be downloaded. Otherwise, `original` size will be downloaded instead of missing size.
+
+    ```{seealso}
+    [`--size` parameter](size-parameter)
+    ```
+
+(live-photo-size-parameter)=
+`--live-photo-size X`
+
+:   Customizes size of the live photo assets to download.
+
+(skip-videos-parameter)=
+`--skip-videos`
+
+:   If specified, video assets will not be processed
+
+(skip-live-photos-parameter)=
+`--skip-live-photos`
+
+:   If specified, live photo assets will not be processed
+
+(auto-delete-parameter)=
+`--auto-delete`
+
+:   If specified, assets deleted in iCloud (actually moved to Recently Deleted album), will also be deleted locally.
+
+    ```{seealso}
+    [Modes of operation](mode)
+    ```
+
+(delete-after-download-parameter)=
+`--delete-after-download`
+
+:   If specified, assets downloaded locally will be deleted in iCloud (actually moved to Recently Deleted album).
+
+    ```{seealso}
+    [Modes of operation](mode)
+    ```
+(only-print-filenames-parameter)=
+`--only-print-filenames`
+
+:   If specified, no downloading will occur, but only file paths printed in the output (no other info goes into output either).
+
+    ```{seealso}
+    [`--dry-run` parameter](dry-run-parameter)
+    ```
+(folder-structure-parameter)=
+`--folder-structure X`
+
+:   Specifies sub folder naming scheme. 
+
+    ```{seealso}
+    Details in [Folder structure](naming) section.
+    ```
+
+(set-exif-datetime-parameter)=
+`--set-exif-datetime`
+
+:   If specified, EXIF data for the image will be updated with date/time of the assets take/created. Only if EXIF does not exist already in the asset.
+
+(no-progress-bar-parameter)=
+`--no-progress-bar`
+
+:   If specified, progress bar is suppressed. Valuable when streaming output to file
+
+(keep-unicode-in-filenames-parameter)=
+`--keep-unicode-in-filenames`
+
+:   If specified, unicode chars will be preserved in filenames. Otherwise they are removed (default).
+
+(live-photo-mov-filename-policy-parameter)=
+`--live-photo-mov-filename-policy X`
+
+:   Customizes naming of the video portion of the live photos.
+
+    ```{seealso}
+    Details in [Live Photo](naming) section.
+    ```
+
+(align-raw-parameter)=
+`--align-raw X`
+
+:   Customizes treating of the RAW+JPEG assets.
+
+    ```{seealso}
+    Details in [RAW+JPEG](raw) section.
+    ```
+
+(password-provider-parameter)=
+`--password-provider X`
+
+:   Customizes intake of the password for iCloud authentication.
+
+    ```{seealso}
+    Details in [Password providers](authentication) section.
+    ```
+(mfa-provider-parameter)=
+`--mfa-provider X`
+
+:   Customizes intake of the multi-factor authentication (MFA) code for iCloud authentication.
+
+    ```{seealso}
+    Details in [MFA providers](authentication) section.
+    ```
+
+
+TODO: SMTP & Notification params

docs/size.md

@@ -23,7 +23,7 @@ Assets for sizes other than original will have suffix added to their name, e.g.
 ```
 
 Image edits are represented as a special size `adjusted`. Two common use cases related to edits:
-- Download only edited version: use `--size adjusted` parameter
+- Download edited version or original if it was not edited: use `--size adjusted` parameter
 - Download edit and original: use `--size adjusted --size original` parameters. Edits will have `-adjusted` suffix added if file extension is the same as original.
 
 ```{note}