Merge pull request #3071 from plotly/update-docstrings

Add docs for `get_asset_url`

dash/_get_paths.py

@@ -5,6 +5,13 @@
 
 
 def get_asset_url(path):
+    """
+    Return the URL for the provided `path` in the assets directory.
+
+    `dash.get_asset_url` is not compatible with Dash Snapshots.
+    Use `get_asset_url` on the app instance instead: `app.get_asset_url`.
+    See `app.get_asset_url` for more information.
+    """
     return app_get_asset_url(CONFIG, path)
 
 
@@ -59,6 +66,9 @@ def display_content(path):
         if page_name == "page-2":
             return chapters.page_2
     ```
+
+    `dash.get_relative_path` is not compatible with Dash Snapshots. Use
+    `get_relative_path` on the app instance instead: `app.get_relative_path`.
     """
     return app_get_relative_path(CONFIG.requests_pathname_prefix, path)
 

dash/dash.py

@@ -1547,6 +1547,33 @@ def _hash(script):
         ]
 
     def get_asset_url(self, path):
+        """
+        Return the URL for the provided `path` in the assets directory.
+
+        If `assets_external_path` is set, `get_asset_url` returns
+        `assets_external_path` + `assets_url_path` + `path`, where
+        `path` is the path passed to `get_asset_url`.
+
+        Otherwise, `get_asset_url` returns
+        `requests_pathname_prefix` + `assets_url_path` + `path`, where
+        `path` is the path passed to `get_asset_url`.
+
+        Use `get_asset_url` in an app to access assets at the correct location
+        in different environments. In a deployed app on Dash Enterprise,
+        `requests_pathname_prefix` is the app name. For an app called "my-app",
+        `app.get_asset_url("image.png")` would return:
+
+        ```
+        /my-app/assets/image.png
+        ```
+
+        While the same app running locally, without
+        `requests_pathname_prefix` set, would return:
+
+        ```
+        /assets/image.png
+        ```
+        """
         return _get_paths.app_get_asset_url(self.config, path)
 
     def get_relative_path(self, path):