shotgunsoftware · martinminsel · Mar 14, 2019 · Mar 14, 2019 · Mar 15, 2019 · Mar 15, 2019
diff --git a/.flake8 b/.flake8
diff --git a/README.md b/README.md
@@ -1,67 +1,13 @@
-# tk-framework-adobe
+[![Reference Documentation](http://img.shields.io/badge/doc-reference-blue.svg)](http://developer.shotgunsoftware.com/tk-framework-adobe)
+[![Linting](https://img.shields.io/badge/PEP8%20by-Hound%20CI-a873d1.svg)](https://houndci.com)
 
-A framework for Adobe engines
-
-
-## Development
-
-### How to set up your development environment
-
-- To setup the development environment for this project, you will need to obtain the [**ZXPSignCmd**](https://labs.adobe.com/downloads/extensionbuilder3.html) tool provided by Adobe. 
-- Once you have logged in using your existing Adobe user account, download the **CC Extensions Signing Toolkit**, which will provide you with the necessary executable.
-- If you are developing on a **Mac**, please set all necessary variables in `dev/env.mk`.
-- If you are developing on **Windows**, please set all necessary variables in `dev\env.cmd`
-
-
-### To install the CEP extension for testing without signing:
-
-```
-cd path/to/tk-adobe-framework
-cd dev
-make test
-```
-
-### To sign the CEP extension
-
-```
-cd path/to/tk-adobe-framework
-cd dev
-make sign
-```
-
-
-### To create a certificate for use when signing the CEP extension
-
-```
-cd path/to/tk-adobe-framework
-cd dev
-make create_certificate
-```
-
-**Note:** In the case where the configured `CERTIFICATE_FILE` does not exist, the create_certificate command will be automatically run as part of the _sign_ target.
-
-
-### To remove the latest signed zxp file
-
-```
-cd path/to/tk-adobe-framework
-cd dev
-make clean
-```
-
-### Notes on editing the env files (`env.mk` and `env.cmd`)
-
-Changes to the env files (`env.mk` and `env.cmd`) will typically not be tracked in git. The information contained in these files is specific to a particular development environment, so tracking changes to that data in git is undesirable.
-
-If you need to make changes to these files, you can use the following commands:
-
-```
-git update-index --no-skip-worktree dev/env.mk dev/env.cmd
-git add dev\env.*
-git commit -m "your message"
-git update-index --skip-worktree dev/env.mk dev/env.cmd
-```
-
-Please be aware that these files contain potentially-sensitive information, such as a certificate password. When making changes to these files and pushing them to a git repository, be sure that you've removed any data that might be considered confidential.
+## Documentation
+This repository is a part of the Shotgun Pipeline Toolkit.
 
+- For more information about this app and for release notes, *see the wiki section*.
+- For API Reference, see http://developer.shotgunsoftware.com/tk-framework-adobe
+- For general information and documentation, click here: https://support.shotgunsoftware.com/entries/95441257
+- For information about Shotgun in general, click here: http://www.shotgunsoftware.com/toolkit
 
+## Have a Question?
+Don't hesitate to contact us! You can find us on [email protected]
diff --git a/docs/development.rst b/docs/development.rst
@@ -0,0 +1,62 @@
+.. _development:
+
+Framework Development
+==========================
+
+This section covers how to make changes to as well as how to deploy the Adobe framework.
+
+Setting up your dev environment
+-------------------------------
+
+To setup the development environment for this project, you will need to obtain the
+`ZXPSignCmd <https://labs.adobe.com/downloads/extensionbuilder3.html>`_ tool provided
+by Adobe. Once you have logged in using your existing Adobe user account,
+download the **CC Extensions Signing Toolkit**, which will provide you with the necessary executables.
+
+- If you are developing on a *Mac* please set all necessary variables in `dev/env.mk`.
+- On *Windows* please fill all necessary variables in `dev\env.cmd`
+
+
+Building and signing the extension
+----------------------------------
+
+Once set up, you can test and sign with the following targets:
+
+.. note::
+    Be sure to run all of the following commands from the top-level directory of this project.
+
+- To install the CEP extension for testing without signing:
+
+    .. code-block:: shell
+
+        cd dev
+        make test
+
+- To sign the CEP extension:
+
+    .. code-block:: shell
+
+        cd dev
+        make sign
+
+- To create a certificate for use when signing the CEP extension:
+
+    .. code-block:: shell
+
+        cd dev
+        make create_certificate
+
+    .. note::
+        In the case where the configured ``CERTIFICATE_FILE`` does not exist, the ``create_certificate``
+        command will be automatically run as part of the process.
+
+
+- To remove the latest signed zxp file:
+
+    .. code-block:: shell
+
+        cd dev
+        make clean
+
+
+
diff --git a/docs/engine_development.rst b/docs/engine_development.rst
@@ -0,0 +1,71 @@
+Developing Adobe Engines
+========================
+
+This section explains you can use the Adobe Framework when writing an Adobe engine.
+
+In your engine, load and initialize the framework::
+
+    # import the framework module
+    adobe_bridge = sgtk.platform.import_framework(
+        "tk-framework-adobe",
+        "tk_framework_adobe.adobe_bridge"
+    )
+    AdobeBridge = adobe_bridge.AdobeBridge
+
+    # get the adobe instance. it may have been initialized already by a
+    # previous instance of the engine. if not, initialize a new one.
+    adobe = AdobeBridge.get_or_create(
+        identifier='tk-myengine',
+        logger=self.logger, # engine logger
+    )
+
+    # connect to all the adobe bridge signals
+    adobe.logging_received.connect(self._handle_logging)
+    adobe.command_received.connect(self._handle_command)
+    adobe.active_document_changed.connect(self._handle_active_document_change)
+    adobe.run_tests_request_received.connect(self._run_tests)
+    adobe.state_requested.connect(self.__send_state)
+
+    # Adobe API will be accessible via the adobe object
+    temp_thumb_file = adobe.File('/tmp/foo.jpeg')
+    save_for_web = adobe.ExportType.SAVEFORWEB
+    export_options = adobe.ExportOptionsSaveForWeb()
+    adobe.app.activeDocument.exportDocument(temp_thumb_file, save_for_web, export_options)
+
+
+The API exposed via the ``adobe`` bridge will depend on the Application that the framework is connecting to.
+The above example shows Photoshop - in this case, the API is
+defined `here <http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/photoshop/pdfs/photoshop-cc-javascript-ref-2015.pdf>`_.
+
+
+Adobe Communicator
+------------------
+
+This is the main object that the Framework exposes. It is responsible for bringing
+the entire global Adobe API javascript scope recursively into python. Once an instance
+of the AdobeBridge class has been created, this instance can be
+used as entry point to javascript-objects inside the Adobe host.
+The instance will always return ProxyWrapper objects, that represent javascript objects or functions.
+
+.. autoclass:: python.tk_framework_adobe.adobe_bridge.AdobeBridge
+    :inherited-members:
+    :members:
+    :exclude-members: save_as, save_as_psb
+
+
+Exceptions
+----------
+
+.. autoclass:: python.tk_framework_adobe.adobe_bridge.RPCTimeoutError
+
+
+Utilities
+---------
+
+In order to simplify the engine installation logic in the startup.py of the engine, the following method is provided.
+
+.. automodule:: python.tk_framework_adobe_utils.startup
+    :members: ensure_extension_up_to_date
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,6 +3,15 @@ The Shotgun Adobe Framework
 
 The Shotgun Adobe Framework contains a common integration platform for Adobe Products,
 unifying and simplifying the process of writing a Shotgun Toolkit integration for an
-Application that is part of the Adobe Suite.
+Application that is part of the Adobe Suite. On the following pages you will get
+more information about this framework and its specialities.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   development
+   engine_development
 
-More documentation coming soon.