diff --git a/website/docs/addon_kitsu_admin.md b/website/docs/addon_kitsu_admin.md index 0f48b4bb..f17fde49 100644 --- a/website/docs/addon_kitsu_admin.md +++ b/website/docs/addon_kitsu_admin.md @@ -17,48 +17,132 @@ import TabItem from '@theme/TabItem'; Kitsu is a great open source production tracker and can be used for project management instead of Ftrack. This documentation assumes that you are familiar with Kitsu and its basic principles. If you're new to Kitsu, we recommend having a thorough look at [Kitsu Official Documentation](https://kitsu.cg-wire.com/). -## Prepare Kitsu for AYON +:::info prerequisites +- Having Kitsu set up and running.
For more info refer to [official installation guide](https://zou.cg-wire.com/) or [community kitsu docker](https://github.com/EmberLightVFX/Kitsu-for-Docker) +- Having [AYON Server Host (ASH)](https://github.com/ynput/ash) set up and running. +::: -### Server URL -If you want to connect Kitsu to AYON you have to set the `Server` url in Kitsu settings. And that's all! -This setting is available for all the users of the AYON instance. +## Kitsu Addon Installation -## Synchronize -Updating OP with Kitsu data is executed running the `sync-service`, which requires to provide your Kitsu credentials with `-l, --login` and `-p, --password` or by setting the environment variables `KITSU_LOGIN` and `KITSU_PWD`. This process will request data from Kitsu and create/delete/update OP assets. -Once this sync is done, the thread will automatically start a loop to listen to Kitsu events. +### Addon Market + +If you have already connected your ayon instance to Ynput cloud, you would be able to get the addon from Addon Market. + +![Addon Market](assets/kitsu/admin/kitsu_addon_market.png) + +### Manual Installation +Another method is to get it from Github releases and install it manually. + +- [Kitsu Addon Github Releases](https://github.com/ynput/ayon-kitsu/releases) + +| Download Addon | Install Addon | +|--|--| +| ![Kitsu GH Releases](assets/kitsu/admin/kitsu_gh_releases.png) | ![AYON Install AYON](assets/kitsu/admin/ayon_install_addon.png) | -```bash -openpype_console module kitsu sync-service -l me@domain.ext -p my_password -``` +## Preparation for Kitsu Addon +Essential preparation for Kitsu addon to work. -### Events listening -Listening to Kitsu events is the key to automation of many tasks like _project/episode/sequence/shot/asset/task create/update/delete_ and some more. Events listening should run at all times to perform the required processing as it is not possible to catch some of them retrospectively with strong reliability. If such timeout has been encountered, you must relaunch the `sync-service` command to run the synchronization step again. +1. Create New Bundle and set Kitsu addon version +2. Add Kitsu Admin Account to AYON Secrets. +3. Spawn Kitsu service. +4. Set Kitsu Server URL -Connection token is refreshed every week. -### Push to Kitsu -An utility function is provided to help update Kitsu data (a.k.a Zou database) with AYON data if the publishing to the production tracker hasn't been possible for some time. Running `push-to-zou` will create the data on behalf of the user. +### Create Bundle and Set Addon Version +Create new production bundle, Set Kitsu Addon version to your installed version, and finally restart server. + +:::note +As soon as you restart your server, you'll start seeing Empty Kitsu tab. +::: + +### Set Kitsu Admin Account +By default Kitsu addon expects two special keys in AYON secrets. +- `kitsu_email` +- `kitsu_password` + +![](assets/kitsu/admin/kitsu_admin_account.png) + + +### Spawn Kitsu service +From Services, Create New Service. + :::caution -This functionality cannot deal with all cases and is not error proof, some intervention by a human being might be required. +Kitsu service should be the same version as your Kitsu addon version. +If you already have a running Kitsu service, you can simply Right-click, delete it and create new one. ::: -```bash -openpype_console module kitsu push-to-zou -l me@domain.ext -p my_password -``` +![](assets/kitsu/admin/kitsu_service.png) -## Integrate Kitsu Note -Task status can be automatically set during publish thanks to `Integrate Kitsu Note`. This feature can be configured in: +### Server URL + +:::tip +If you're operating your Kitsu instance with Docker and encounter a connection error, it's likely due to an incorrect IP address. Make sure to use the right one. For additional details, visit this community post: [Kitsu connection error (Could not login to Kitsu)](https://community.ynput.io/t/kitsu-connection-error-could-not-login-to-kitsu/1556/13). +::: + +As soon as you set the `Server` url in Kitsu settings. And that's all! +- `ayon+settings://kitsu/server` + +![](assets/kitsu/admin/kitsu_server_url.png) + + +## Synchronize +Synchronization is two step process. +From Kitsu Tab: +1. Click `Pair project` +2. Click `Sync now` -`Admin -> Studio Settings -> Project Settings -> Kitsu -> Integrate Kitsu Note`. +> Currently, Synchronization is one-way only **Kitsu ➜ AYON**. -There are three settings available: -- `Set status on note` -> turns on and off this integrator. -- `Note shortname` -> Which status shortname should be set automatically (Case sensitive). -- `Status conditions` -> Conditions that need to be met for kitsu status to be changed. You can add as many conditions as you like. There are two fields to each conditions: `Condition` (Whether current status should be equal or not equal to the condition status) and `Short name` (Kitsu Shortname of the condition status). +| Kitsu Productions | Kitsu Tab | +|--|--| +| ![](assets/kitsu/admin/kitsu_tab_sync_2.png) | ![](assets/kitsu/admin/kitsu_tab_sync.png) | -![Integrate Kitsu Note project settings](assets/integrate_kitsu_note_settings.png) +## Kitsu Addon Configuration + +### Integrate Kitsu Note +Task status can be automatically set during publish thanks to `Integrate Kitsu Note`. This feature can be configured in: +- `ayon+settings://kitsu/publish/IntegrateKitsuNote`. + +Available settings: +- `Set status on note`: Turns on and off this integrator. +- `Note shortname`: Which status shortname should be set automatically (Case sensitive). +- `Status change conditions`: Conditions that need to be met for kitsu status to be changed. You can add as many conditions as you like. + - `Status Conditions`: There are two fields to each conditions: + - `Condition` (Whether current status should be equal or not equal to the condition status) + - `Short name` (Kitsu Shortname of the condition status). + - `Product type requirements` + - `Condition` (Whether published product type should be equal or not equal to the condition status) + - `Product type` (AYON Product type) +- `Custom Comment Template` -> when enabled, AYON publisher will use this template as Kitsu comment. You can use markdown as it's supported by Kitsu. + + +![Integrate Kitsu Note project settings](assets/kitsu/admin/integrate_kitsu_note_settings.png) + +#### Custom Comment Template example +Here's an example template that makes a nice table. +- `| comment | version | product type | name |\n|--|--|--|--|\n| {comment} | {version} | {productType} | {name} |` + +:::tip Custom Comment Template +Artists need only to provide comment in publisher UI. +And, `Integrate Kitsu Note` will do the hard work for them. +![](assets/kitsu/admin/kitsu_comment_publisher.png) + +![](assets/kitsu/admin/kitsu_comment_template.png) +::: +### Sync Settings + +- `Delete Projects`: Enabling 'Delete projects' will remove projects on Ayon when they get deleted on Kitsu +- `Sync users` Sync Kitsu Users, their passwords and map Kitsu roles to AYON roles. +- `Default sync info` + - Tasks (Name, Short Name, Icon) + - Statuses (Short Name, State, Icon) ## Q&A ### Is it safe to rename an entity from Kitsu? +:::caution +While changing the names of entities is allowed, Be aware it doesn't change the existent file names or publishes. +::: + Absolutely! Entities are linked by their unique IDs between the two databases. -But renaming from the OP's Project Manager won't apply the change to Kitsu, it'll be overridden during the next synchronization. +- If you rename an entity in the AYON project editor, this change won't show up in Kitsu. Instead, it will be replaced with the original name when the next sync happens. +- When you rename an entity directly in Kitsu, the new name will be updated in AYON during the upcoming synchronization. diff --git a/website/docs/addon_kitsu_artist.md b/website/docs/addon_kitsu_artist.md index 1cb60484..46e5d8be 100644 --- a/website/docs/addon_kitsu_artist.md +++ b/website/docs/addon_kitsu_artist.md @@ -17,8 +17,24 @@ import versions from '@site/docs/assets/json/Ayon_addons_version.json' 1. Launch AYON, the `Kitsu Credentials` window will open automatically, if not, or if you want to log-in with another account, go to systray AYON icon and click on `Kitsu Connect`. 2. Enter your credentials and press *Ok*: - ![kitsu-login](assets/kitsu/kitsu_credentials.png) + ![kitsu-login](assets/kitsu/artist/kitsu_credentials.png) :::tip In Kitsu, All the publish actions executed by `pyblish` will be attributed to the currently logged-in user. -::: \ No newline at end of file +::: + +## Integrate Kitsu Note and Review + +If they are enabled in Kitsu addon settings. +- Your publish comment will be used as Kitsu note. +- When publishing a Review or Render, publisher can upload them to kitsu. + +:::note Notes +- Depending on the kitsu addon configuration, publisher also can update the task status. +- Admins are able to configure `Custom Comment Template`, [learn More](addon_kitsu_admin#custom-comment-template-example). +::: + +| Publish Comment | Kitsu Note and Review | +|--|--| +| ![kitsu Note 1](assets/kitsu/artist/kitsu_note_1.png) | ![kitsu Note 2](assets/kitsu/artist/kitsu_note_2.png) | + diff --git a/website/docs/assets/integrate_kitsu_note_settings.png b/website/docs/assets/integrate_kitsu_note_settings.png deleted file mode 100644 index 127e79ab..00000000 Binary files a/website/docs/assets/integrate_kitsu_note_settings.png and /dev/null differ diff --git a/website/docs/assets/json/Ayon_addons_version.json b/website/docs/assets/json/Ayon_addons_version.json index eea9e96f..d686c17b 100644 --- a/website/docs/assets/json/Ayon_addons_version.json +++ b/website/docs/assets/json/Ayon_addons_version.json @@ -15,7 +15,7 @@ "Harmony_Badge" : "[![Harmony Addon - 0.1.2](https://img.shields.io/badge/Harmony_Addon-0.1.2-8bcbb8)](https://github.com/ynput/OpenPype/tree/develop/openpype/hosts/harmony)", "Hiero_Badge" : "[![Hiero Addon - 0.1.0](https://img.shields.io/badge/Hiero_Addon-0.1.0-fab41a)](https://github.com/ynput/OpenPype/tree/develop/openpype/hosts/hiero)", "Houdini_Badge" : "[![Houdini addon - 0.2.12](https://img.shields.io/badge/Houdini_Addon-0.2.12-FF4713?logo=houdini)](https://github.com/ynput/ayon-core/tree/develop/client/ayon_core/hosts/houdini)", - "Kitsu_Badge" : "[![Kitsu Addon - 0.1.3](https://img.shields.io/badge/Kitsu_Addon-0.1.3-e56b27)](https://github.com/ynput/ayon-kitsu)", + "Kitsu_Badge" : "[![Kitsu Addon - 1.1.0](https://img.shields.io/badge/Kitsu_Addon-1.1.0-e56b27)](https://github.com/ynput/ayon-kitsu)", "Max_Badge" : "[![3Ds Max Addon - 0.1.2](https://img.shields.io/badge/3Ds_Max_Addon-0.1.2-3190b2)](https://github.com/ynput/OpenPype/tree/develop/openpype/hosts/max)", "Maya_Badge" : "[![Maya addon - 0.1.6](https://img.shields.io/badge/Maya_Addon-0.1.6-3190b2)](https://github.com/ynput/OpenPype/tree/develop/openpype/hosts/maya)", "Muster_Badge" : "[![Muster Addon - 0.1.1](https://img.shields.io/badge/Muster_Addon-0.1.1-1589b8)](https://github.com/ynput/OpenPype/tree/develop/openpype/modules/muster)", diff --git a/website/docs/assets/kitsu/admin/ayon_install_addon.png b/website/docs/assets/kitsu/admin/ayon_install_addon.png new file mode 100644 index 00000000..b5e23786 Binary files /dev/null and b/website/docs/assets/kitsu/admin/ayon_install_addon.png differ diff --git a/website/docs/assets/kitsu/admin/integrate_kitsu_note_settings.png b/website/docs/assets/kitsu/admin/integrate_kitsu_note_settings.png new file mode 100644 index 00000000..1b4a75dd Binary files /dev/null and b/website/docs/assets/kitsu/admin/integrate_kitsu_note_settings.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_addon_market.png b/website/docs/assets/kitsu/admin/kitsu_addon_market.png new file mode 100644 index 00000000..68aff04a Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_addon_market.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_admin_account.png b/website/docs/assets/kitsu/admin/kitsu_admin_account.png new file mode 100644 index 00000000..3a4b5dce Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_admin_account.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_comment_publisher.png b/website/docs/assets/kitsu/admin/kitsu_comment_publisher.png new file mode 100644 index 00000000..a5817523 Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_comment_publisher.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_comment_template.png b/website/docs/assets/kitsu/admin/kitsu_comment_template.png new file mode 100644 index 00000000..4219e7eb Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_comment_template.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_gh_releases.png b/website/docs/assets/kitsu/admin/kitsu_gh_releases.png new file mode 100644 index 00000000..7ebc17d2 Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_gh_releases.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_server_url.png b/website/docs/assets/kitsu/admin/kitsu_server_url.png new file mode 100644 index 00000000..9a19f8f9 Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_server_url.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_service.png b/website/docs/assets/kitsu/admin/kitsu_service.png new file mode 100644 index 00000000..dceca16d Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_service.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_tab_sync.png b/website/docs/assets/kitsu/admin/kitsu_tab_sync.png new file mode 100644 index 00000000..a4b521cd Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_tab_sync.png differ diff --git a/website/docs/assets/kitsu/admin/kitsu_tab_sync_2.png b/website/docs/assets/kitsu/admin/kitsu_tab_sync_2.png new file mode 100644 index 00000000..6b4bac21 Binary files /dev/null and b/website/docs/assets/kitsu/admin/kitsu_tab_sync_2.png differ diff --git a/website/docs/assets/kitsu/kitsu_credentials.png b/website/docs/assets/kitsu/artist/kitsu_credentials.png similarity index 100% rename from website/docs/assets/kitsu/kitsu_credentials.png rename to website/docs/assets/kitsu/artist/kitsu_credentials.png diff --git a/website/docs/assets/kitsu/artist/kitsu_note_1.png b/website/docs/assets/kitsu/artist/kitsu_note_1.png new file mode 100644 index 00000000..74f7ac20 Binary files /dev/null and b/website/docs/assets/kitsu/artist/kitsu_note_1.png differ diff --git a/website/docs/assets/kitsu/artist/kitsu_note_2.png b/website/docs/assets/kitsu/artist/kitsu_note_2.png new file mode 100644 index 00000000..ebf3d882 Binary files /dev/null and b/website/docs/assets/kitsu/artist/kitsu_note_2.png differ