[BUG] ensure app temp dir exists before loading sources

[BUG] only set selection clipboard on OS that supports it
[ENH] display absolute path to program in about dialog
[ENH] theme/icon support, add missing icons, move off django icons
[EHN] Rewrite file parsers to move read/write logic out of init
[MNT] rm deprecated -dark flag
[MNT] better defaults for diff and text editor on Windows
[DOC] clarify install instructions

Signed-off-by: mds-dwa <mark.sandell@dreamworks.com>

README.md

@@ -9,7 +9,7 @@ USD Manager is an open-source, python-based Qt tool for browsing, managing, and
 combining the best features from your favorite web browser and text editor into one application, with hooks to deeply
 integrate with other pipeline tools. It is developed and maintained by [DreamWorks Animation](http://www.dreamworksanimation.com)
 for use with USD and other hierarchical, text-based workflows, primarily geared towards feature film production. While
-primarily designed around PyQt4, USD Manager uses the Qt.py compatibility library to allow working with PyQt4, PyQt5,
+originally designed around PyQt4, USD Manager uses the Qt.py compatibility library to allow working with PyQt4, PyQt5,
 PySide, or PySide2 for Qt bindings.
 
 ![USD Manager screenshot](docs/_static/screenshot_island.png?raw=true "USD Manager")
@@ -42,8 +42,14 @@ Installing USD Manager
 Requirements
 ------------
 
-usdmanager requires Python 2, [Qt.py](https://github.com/mottosso/Qt.py) and [setuptools](https://github.com/pypa/setuptools)
-(can be handled by setup.py), and one of Qt.py's 4 supported Qt bindings, which will need to be installed separately.
+usdmanager requires [Python](https://www.python.org/) 2 (for Python 3, see the
+[python3 branch](https://github.com/dreamworksanimation/usdmanager/tree/python3)),
+[Qt.py](https://github.com/mottosso/Qt.py) and [setuptools](https://github.com/pypa/setuptools)
+(can be handled by setup.py), and one of Qt.py's four supported Qt bindings, which will need to be installed separately.
+
+Additionally, an installation of [USD](https://graphics.pixar.com/usd) itself is recommended but not required for all use cases.
+Installing USD provides access to file path resolvers, non-ASCII USD formats, and plug-ins like usdview.
+All USD versions should be supported.
 
 Install with setup.py
 ---------------------
@@ -58,7 +64,7 @@ For a personal install, try:
 python setup.py install --user
 ```
 
-Studios with significant python codebases or non-trivial installs may need to customize setup.py
+Studios with significant python codebases or non-trivial installs may need to customize [setup.py](setup.py).
 
 Your PATH and PYTHONPATH will need to be set appropriately to launch usdmanager,
 and this will depend on your setup.py install settings.

docs/development.md

@@ -24,7 +24,9 @@ Supported keys include:
 - **appURL _(str)_** - Documentation URL. Defaults to the public GitHub repository.
 - **defaultPrograms _({str: str})_** - File extension keys with the command to open the file type as the values.
 - **diffTool _(str)_** - Diff command. Defaults to xdiff.
-- **iconTheme _(str)_** - QtGui.QIcon theme name. Defaults to crystal_project.
+- **iconTheme _(str)_** - QtGui.QIcon theme name. Defaults to crystal_project. Can be overridden by iconThemes for a
+specific app theme.
+- **iconThemes _(dict)_** - QtGui.QIcon theme name to use per theme the app supports ("light" and "dark")
 - **textEditor _(str)_** - Text editor to use when opening files externally if $EDITOR environment variable is
 not set. Defaults to nedit.
 - **themeSearchPaths _([str])_** - Paths to prepend to QtGui.QIcon's theme search paths.
@@ -43,7 +45,10 @@ Example app config JSON file:
         "tx": "rez-run openimageio_arras -- iv"
     },
     "diffTool": "python /usr/bin/meld",
-    "iconTheme": "gnome",
+    "iconThemes": {
+        "light": "crystal_project",
+        "dark": "gnome"
+    },
     "textEditor": "gedit",
     "themeSearchPaths": []
 }
@@ -117,13 +122,13 @@ class CustomExample(Plugin):
 
 ## Icons
 
-Most icons in the app come from themes pre-installed on your system, ideally following the
+Some icons in the app come from themes pre-installed on your system, ideally following the
 [freedesktop.org standards](https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html).
 The preferred icon set that usdmanager was originally developed with is Crystal Project Icons. These icons are licensed
-under LGPL and available via pypi and GitHub here: https://github.com/ambv/django-crystal-small. While not required for
-the application to work, if you would like these icons to get the most out of the application, please install them to a
-directory named crystal_project under one of the directories listed by `Qt.QtGui.QIcon.themeSearchPaths()` (e.g.
-/usr/share/icons/crystal_project).
+under LGPL and available via PyPI and GitHub here: https://github.com/mds-dwa/crystal-small. While not required for
+the application to work, if you would like these icons to get the most out of the application, please ensure crystal-small
+is installed via pip (already part of the default setup) or install them to a directory named crystal_project under one
+of the directories listed by `Qt.QtGui.QIcon.themeSearchPaths()` (e.g. /usr/share/icons/crystal_project).
 
 Additional icons for custom plug-ins can be placed in the plugins directory and then added to the
 [usdmanager/plugins/images.qrc](https://github.com/dreamworksanimation/usdmanager/blob/master/usdmanager/plugins/images.qrc) file. After adding a file to images.rc, run the

docs/installation.md

@@ -16,10 +16,14 @@ have not been as heavily tested. Notes to help with installation on specific ope
 - [Common Problems](#common-problems)
 
 ## Prerequisites
-- Install Python 2 ([https://www.python.org/downloads/](https://www.python.org/downloads/))
+- Install Python 2 ([https://www.python.org/downloads/](https://www.python.org/downloads/)), or 3 if on the python3 branch.
   * **Windows:** Ensure the install location is part of your PATH variable (newer installs should have an option for this)
 - Install one of the recommended Python Qt bindings
   * **Python 2:** PyQt4 or PySide
+  * **Python 3:** PyQt5 or PySide2, example:
+    ```
+    pip install PySide2
+    ```
 
 ## Install with setup.py
 
@@ -65,23 +69,20 @@ and this will depend on your setup.py install settings.
 3. Customize usdmanager/config.json if needed.
 4. Run ```python setup.py install``` (may need the ```--user``` flag)
 
-If setup.py complains about missing setuptools, you can install it via pip. If you installed a new enough python-2 version, pip should already be handled for you, but you may still need to add it to your PATH. pip should already live somewhere like this (C:\Python27\Scripts\pip.exe), and you can permanently add it to your environment with: ```setx PATH "%PATH%;C:\Python27\Scripts"```
+If setup.py complains about missing setuptools, you can install it via pip. If you installed a new enough python version, pip should already be handled for you, but you may still need to add it to your PATH. pip should already live somewhere like this (C:\Python27\Scripts\pip.exe or C:\Users\username\AppData\Local\Microsoft\WindowsApps\pip.exe), but if needed, you can permanently add it to your environment with this (adjusting the path as needed): ```setx PATH "%PATH%;C:\Python27\Scripts"```
 
 1. Upgrade pip if needed
  1. Launch Command Prompt in Administrator mode
  2. Run ```pip install pip --upgrade``` (may need the ```--user``` flag)
 2. Install setuptools if needed
  1. Run ```pip install setuptools```
 3. Re-run the setup.py step above for usdmanager
-4. If you don't modify your path, you should now be able to run something like this to launch the program: ```python C:\Python27\Scripts\usdmanager```
+4. If you don't modify your path, you should now be able to run something like this to launch the program: ```python C:\Python27\Scripts\usdmanager``` or from the install directory itself, e.g. ``` python .\build\scripts-3.8\usdmanager```
 
 #### Known Issues
-- Drive letter may show doubled-up in address bar (e.g. C:C:/my_file.txt)
+- Since this is not installed as an entirely self-contained package, the application name (and icon) will by Python, not USD Manager.
 
 ## Common Problems
-- Missing icons (may still be missing some even after this!)
-  * ```pip install django-crystal-small``` (this also installs django by default, which you may not want)
-  * Add installed path to your downloaded usdmanager/config.json file, then re-run the setup.py install. You'll need a line similar to this in your config.json: ```"themeSearchPaths": ["C:\\Python27\\Lib\\site-packages\\django_crystal_small\\static\\crystal"]```
 - Can't open files in external text editor
-  * In Preferences, try setting your default text editor
-  * **Windows:** Try ```notepad.exe``` or ```"C:\Windows\notepad.exe"``` (including the quotation marks)
+  * In Preferences, update your default text editor
+  * **Windows:** Try ```notepad```, ```notepad.exe```, or ```"C:\Windows\notepad.exe"``` (including the quotation marks on that last one)

setup.py

@@ -68,6 +68,7 @@
     data_files=[("usdmanager", ["usdmanager/usdviewstyle.qss"])],
     scripts=glob("scripts/*"),
     install_requires=[
+        "crystal_small",  # Default icons
         "Qt.py>=1.1",
         "setuptools",  # For pkg_resources
     ],