Feature/pinning file support

Docs/Ayon_Docs/Admin_Docs.md

@@ -36,33 +36,42 @@ distributing Usd and Ayon Libs:
 
 ## Configuration
 
-there is a list of things that you can configure in the server settings to
+There is a list of things that you can configure in the server settings to
 achieve the optimal setup for your studio. In most cases you will probably not
-need to touch them tho.
+need to touch them though.
 
 #### LakeFs Config
 
-**LakeFs Settings:** `ayon+settings://ayon_usd/lakefs`\
-LakeFs is the backend of our bin distribution system the addon will use the
-specified server to download the resolvers and AyonUsdLibs from LakeFs.
+**LakeFs Settings:**
+
+The `ayon+settings://ayon_usd/lakefs` section configures the backend
+for our bin distribution system, which uses the specified server to download
+resolvers and AyonUsdLibs from LakeFs.
+
 
 **LakeFs Server Uri:**
-`ayon+settings://ayon_usd/lakefs/server_repo`\
-this is the Uri used to host the LakeFs server. the Ynput server can be found at
+
+`ayon+settings://ayon_usd/lakefs/server_repo`
+
+This is the URI used to host the LakeFs server.  You can find the Ynput server at
 `https://lake.ayon.cloud`
 
-**LakeFs Repository Uri:**
-`ayon+settings://ayon_usd/lakefs/server_repo`\
-this is a LakeFs internal link that also specifies the branch your downloading
-from.\
-this can be great if you want to pin your pipeline to a specific release.
-
-**Asset Resolvers:** `ayon+settings://ayon_usd/lakefs/asset_resolvers`\
-allows you to associate a specific Application name with a specific resolver.\
-we always set up all the resolvers we compile but if you have special App_Names
-in your Applications then you might want to add an App Alias.\
-e.g. if you have hou19.5.xxx setup as a variant for Houdini you can then set 
-it as an alias for the Hou19.5 entry because they share the same resolver.
+**LakeFs Repository URI:**
+
+`ayon+settings://ayon_usd/lakefs/server_repo`
+
+This is a LakeFs internal link that specifies the branch you are downloading
+from. This can be useful if you want to pin your pipeline to a specific release.
+
+**Asset Resolvers:**
+
+`ayon+settings://ayon_usd/lakefs/asset_resolvers`
+
+This allows you to associate a specific Application name with a specific
+resolver. We always set up all the resolvers we compile, but if you have special
+App_Names in your Applications, you might want to add an App Alias. For example,
+if you have "hou19.5.xxx" set up as a variant for Houdini, you can then set it
+as an alias for the Hou19.5 entry because they share the same resolver.
 
 #### Usd Resolver Config
 

Docs/Ayon_Docs/Dev_Docs.md

@@ -18,9 +18,44 @@ Most important Locations.
 
 ### Pinning Support.
 
-The Ayon Usd resolver has a feature we call pinning support. This allows storing
-the current state of an Usd stage in a file to load the data quickly and without
-server interaction on a Farm or any distributed system that might overwhelm or
-impact the server performance.
+`Standalone/Usd/pinning/pinning_file_helper.py`
 
-The rest of this can be found in the pinning support Branch
+The Ayon Usd resolver has a feature we call pinning support.\
+This allows storing the current resolver state for an Usd stage in a file to
+load the frozen stage without server interaction.
+
+`generate_pinning_file`\
+creates a pinning file JSON from a given USD stage
+
+```py
+def generate_pinning_file(
+    entry_usd: str, root_info: Dict[str, str], pinning_file_path: str
+):
+```
+
+Example Code:
+
+```py
+import os
+import ayon_api
+from ayon_usd.standalone.usd.pinning import pinning_file_helper
+
+
+in_usd_file = "/path/to/usd/file.usd"
+root_info = ayon_api.get_project_roots_for_site(os.environ.get("AYON_PROJECT_NAME"))
+
+pinning_file_helper.generate_pinning_file(in_usd_file, root_info, "/path/to/output_file.json")
+```
+
+:::warning USD file entrypoint URI versus filepath The `in_usd_file` can be
+anything that the AyonUsdResolver can resolve, including an AYON URI. However,
+it is important to know that whatever you use as the input must be the input
+when you load the usd.\
+In other words: if you use an URI to generate the pinning file you need to open
+the stage with the same URI, whereas if you use an file path you will need to do
+the same.\
+::: it is generally advised to use an URI as they will never have any system
+specific data in them.\
+The generated pinning file also has a key that will tell you what entry point
+was used to generate the pinning file. You can simply read out this key and use
+it to open a stage with the pinning file `ayon_pinning_data_entry_scene`.

README.md

@@ -12,7 +12,7 @@ You can find Admin and Developer docs under Docs/Ayon_Docs/
 ### Clone the Repo
 
 > **_IMPORTANT_**\
-> This repository uses Git Submodules. Make sure to use the correct `git clone`\
+> This repository uses Git-Submodules. Make sure to use the correct `git clone`\
 > commands accordingly.\
 > `git clone --recurse-submodules https://github.com/ynput/ayon-usd.git`\
 > `git submodule update --init --recursive`

client/ayon_usd/standalone/usd/pinning/__init__.py

@@ -0,0 +1,3 @@
+from ._pinning_file_generation_funcs import generate_pinning_file
+
+__all__ = ["generate_pinning_file"]