Link dialog docs

docs/platform.rst

@@ -915,6 +915,10 @@ What happens in the above calls is that your app widget is parented inside of a
 Sgtk will add additional potential window constructs, menus etc. Whenever the app widget is closed (for example
 using the close() method), the parent window that is used to wrap the widget will automatically close too.
 
+
+
+.. _qdialog-exit-codes:
+
 Modal dialogs and exit codes
 ========================================
 
@@ -935,6 +939,10 @@ property called ``exit_code``. Typically, your code for a modal dialog would loo
 
 The call to self.engine.show_modal() will return the appropriate status code depending on which button was clicked.
 
+
+
+.. _hiding-toolkit-title-bar:
+
 Hiding the default Toolkit title bar
 ========================================
 

python/tank/platform/engine.py

@@ -1835,14 +1835,7 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs):
         The dialog will be created with a standard Toolkit window title bar where
         the title will be displayed.
 
-        .. note:: In some cases, it is necessary to hide the standard Toolkit title
-                  bar. You can do this by adding a property to the widget class you are
-                  displaying::
-
-                        @property
-                        def hide_tk_title_bar(self):
-                            "Tell the system to not show the standard toolkit toolbar"
-                            return True
+        .. seealso:: :ref:`hiding-toolkit-title-bar`
 
         **Notes for engine developers**
 
@@ -1853,19 +1846,24 @@ def hide_tk_title_bar(self):
         Making use of these methods in the correct way allows the base Engine class to manage the
         lifetime of the dialogs and widgets efficiently and safely without you having to worry about it.
 
-        The methods available are listed here in the hierarchy in which they are called::
+        The methods available are listed here in the hierarchy in which they are called:
+
+          - :meth:`~Engine.show_dialog`/:meth:`~Engine.show_modal`
+
+              - :meth:`~Engine._create_dialog_with_widget`
+
+                  - :meth:`~Engine._get_dialog_parent`
+
+                  - :meth:`~Engine._create_widget`
 
-            show_dialog()/show_modal()
-                _create_dialog_with_widget()
-                    _get_dialog_parent()
-                    _create_widget()
-                    _create_dialog()
+                  - :meth:`~Engine._create_dialog`
 
         For example, if you just need to make sure that all dialogs use a specific parent widget
-        then you only need to override _get_dialog_parent() (e.g. the tk-maya engine).
+        then you only need to override :meth:`~Engine._get_dialog_parent` (e.g. the tk-maya engine).
         However, if you need to implement a two-stage creation then you may need to re-implement
-        show_dialog() and show_modal() to call _create_widget() and _create_dialog() directly rather
-        than using the helper method _create_dialog_with_widget() (e.g. the tk-3dsmax engine).
+        :meth:`~Engine.show_dialog` and :meth:`~Engine.show_modal` to call :meth:`~Engine._create_widget`
+        and :meth:`~Engine._create_dialog` directly rather than using the helper method
+        :meth:`~Engine._create_dialog_with_widget` (e.g. the tk-3dsmax engine).
         Finally, if the application you are writing an engine for is Qt based then you may not need
         to override any of these methods (e.g. the tk-nuke engine).
 
@@ -1874,9 +1872,11 @@ def hide_tk_title_bar(self):
         :param widget_class: The class of the UI to be constructed. This must derive from QWidget.
         :type widget_class: :class:`PySide.QtGui.QWidget`
 
-        Additional parameters specified will be passed through to the widget_class constructor.
+        Additional parameters specified will be passed through to the
+        ``widget_class`` constructor.
 
-        :returns: the created widget_class instance
+        :returns: The created ``widget_class`` instance
+        :rtype: PySide.QtGui.QWidget
         """
         if not self.has_ui:
             self.log_error(
@@ -1904,23 +1904,23 @@ def show_modal(self, title, bundle, widget_class, *args, **kwargs):
         The dialog will be created with a standard Toolkit window title bar where
         the title will be displayed.
 
-        .. note:: In some cases, it is necessary to hide the standard Toolkit title
-                  bar. You can do this by adding a property to the widget class you are
-                  displaying::
+        .. seealso::
+
+            - :ref:`qdialog-exit-codes`
 
-                        @property
-                        def hide_tk_title_bar(self):
-                            "Tell the system to not show the standard toolkit toolbar"
-                            return True
+            - :ref:`hiding-toolkit-title-bar`
 
         :param title: The title of the window
         :param bundle: The app, engine or framework object that is associated with this window
         :param widget_class: The class of the UI to be constructed. This must derive from QWidget.
         :type widget_class: :class:`PySide.QtGui.QWidget`
 
-        Additional parameters specified will be passed through to the widget_class constructor.
+        Additional parameters specified will be passed through to the
+        ``widget_class`` constructor.
 
-        :returns: (a standard QT dialog status return code, the created widget_class instance)
+        :returns: :attr:`QDialog.DialogCode <PySide.QtGui.PySide.QtGui.QDialog.DialogCode>`
+            and the created ``widget_class`` instance
+        :rtype: tuple(int, PySide.QtGui.QWidget)
         """
         if not self.has_ui:
             self.log_error(
@@ -1953,24 +1953,19 @@ def show_panel(self, panel_id, title, bundle, widget_class, *args, **kwargs):
         The dialog will be created with a standard Toolkit window title bar where
         the title will be displayed.
 
-        .. note:: In some cases, it is necessary to hide the standard Toolkit title
-                  bar. You can do this by adding a property to the widget class you are
-                  displaying::
-
-                        @property
-                        def hide_tk_title_bar(self):
-                            "Tell the system to not show the standard toolkit toolbar"
-                            return True
+        .. seealso:: :ref:`hiding-toolkit-title-bar`
 
         :param panel_id: Unique identifier for the panel, as obtained by register_panel().
         :param title: The title of the panel
         :param bundle: The app, engine or framework object that is associated with this window
         :param widget_class: The class of the UI to be constructed. This must derive from QWidget.
         :type widget_class: :class:`PySide.QtGui.QWidget`
 
-        Additional parameters specified will be passed through to the widget_class constructor.
+        Additional parameters specified will be passed through to the
+        ``widget_class`` constructor.
 
-        :returns: the created widget_class instance
+        :returns: The created ``widget_class`` instance
+        :rtype: PySide.QtGui.QWidget
         """
         # engines implementing panel support should subclass this method.
         # the core implementation falls back on a modeless window.