[FSTORE-2122] Improve sharing UI

docs/user_guides/fs/sharing/sharing.md

@@ -2,50 +2,72 @@
 
 ## Introduction
 
-Hopsworks allows artifacts (such as feature groups and feature views) to be shared between projects. There are two main use cases for sharing features:
+Hopsworks allows artifacts (such as feature groups and feature views) to be shared between projects.
+There are two main use cases for sharing features:
 
-- **Cross-team collaboration:** When multiple teams work on the same Hopsworks deployment, each team typically has its own set of projects. If team A wants to leverage features built by team B, team B can share their feature groups with team A's project.
+- **Cross-team collaboration:** When multiple teams work on the same Hopsworks deployment, each team typically has its own set of projects.
+  If team A wants to leverage features built by team B, team B can share their feature groups with team A's project.
 
-- **Environment isolation:** By creating separate projects for different stages of the development lifecycle (development, testing, and production), you can ensure that changes in the development project don't impact production features. At the same time, you can share production features to use them when developing new models or additional features.
+- **Environment isolation:** By creating separate projects for different stages of the development lifecycle (development, testing, and production), you can ensure that changes in the development project don't impact production features.
+  At the same time, you can share production features to use them when developing new models or additional features.
 
-## Sharing the entire feature store
-
-You can share your project's entire feature store with another project, granting read-only access to all feature groups.
+## Seeing what is shared
 
-### Step 1: Navigate to sharing settings
+Open the project that owns the feature store.
+In `Project Settings`, the `Feature store sharing` section lists everything the feature store shares, and a sentence at the top summarizes it.
+Only data owners can share, unshare and revoke, so only they get the `Share` button and the trash icons.
+Observers see the same lists read-only, and other members see a note instead, because only data owners and observers can read a project's sharing.
 
-Open the project containing the feature store you want to share. In `Project Settings`, navigate to the `Shared with other projects` section.
+The `Projects` tab lists every project the feature store is shared with.
+A project marked `Entire feature store` can read every feature group, including feature groups created after the share.
+Any other project lists the feature groups shared with it, with either `all features` or the features it can read.
 
 <p align="center">
   <figure>
-    <img src="../../../../assets/images/guides/project/sharing/share_with_other_projects.png" alt="Share Project">
-    <figcaption>Shared with other projects section in Project Settings</figcaption>
+    <img src="../../../../assets/images/guides/project/sharing/share_with_other_projects.png" alt="The Projects tab of the Feature store sharing section, with one project sharing the entire feature store and one with two feature groups">
+    <figcaption>Feature store sharing section in Project Settings</figcaption>
   </figure>
 </p>
 
-### Step 2: Share the feature store
-
-Click `Share feature store` to open the sharing dialog, then select the target project.
+The `Restricted users` tab lists every member with the [Feature store restricted][feature-store-restricted] role who has been granted access, with the feature groups and features each of them can read.
 
 <p align="center">
   <figure>
-    <img src="../../../../assets/images/guides/project/sharing/share_project_dialog.png" alt="Share Project Dialog">
-    <figcaption>Share feature store dialog</figcaption>
+    <img src="../../../../assets/images/guides/fs/sharing/feature_store_sharing_restricted_users.png" alt="The Restricted users tab of the Feature store sharing section, with one user granted two feature groups">
+    <figcaption>Restricted users granted access to feature groups</figcaption>
   </figure>
 </p>
 
-!!! note "Read-only access"
-    Shared feature stores are always read-only. Members of the target project cannot modify any data in the shared feature store.
+Each feature group name links to that feature group's `Sharing` tab.
+
+## Sharing the entire feature store
+
+You can share your project's entire feature store with another project, granting read-only access to all feature groups.
+
+### Step 1: Open the share dialog
+
+In `Project Settings`, click `Share` in the `Feature store sharing` section.
 
-After clicking `Share`, the feature store appears under the `Shared with other projects` section.
+### Step 2: Share the feature store
+
+In `With a project`, select the target project, keep `The entire feature store, including feature groups created later` selected, and click `Share`.
 
 <p align="center">
   <figure>
-    <img src="../../../../assets/images/guides/project/sharing/list_of_shared_projects.png" alt="List of projects this project is shared with">
-    <figcaption>List of projects the feature store is shared with</figcaption>
+    <img src="../../../../assets/images/guides/project/sharing/share_project_dialog.png" alt="The share dialog with a target project selected and the entire feature store option checked">
+    <figcaption>Share the entire feature store</figcaption>
   </figure>
 </p>
 
+!!! note "Read-only access"
+    Shared feature stores are always read-only.
+    Members of the target project cannot modify any data in the shared feature store.
+
+A project holds either the entire feature store or a set of individual feature groups, not both, because the entire feature store already includes every feature group.
+A project that already has feature groups shared with it is listed in the dialog but cannot be selected; unshare those feature groups first.
+
+After clicking `Share`, the project appears in the `Projects` tab marked `Entire feature store`.
+
 ### Using the API to share the feature store
 
 ```python
@@ -68,60 +90,66 @@ fs.unshare("target_project")
 
 ## Sharing a feature group with selected features
 
-For more granular control, you can share individual feature groups and select which features to expose. This allows you to share specific data without granting access to your entire feature store.
+For more granular control, you can share individual feature groups and select which features to expose.
+This allows you to share specific data without granting access to your entire feature store.
 
 ### Step 1: Navigate to the feature group
 
 In the `Feature Groups` section, select the feature group you want to share and click the `Sharing` tab.
 
 <p align="center">
   <figure>
-    <img src="../../../../assets/images/guides/project/sharing/share_feature_group.png" alt="Share Feature Group">
+    <img src="../../../../assets/images/guides/project/sharing/share_feature_group.png" alt="The Sharing tab of a feature group that is not shared yet, with the Share and Grant access buttons">
     <figcaption>Feature group sharing tab</figcaption>
   </figure>
 </p>
 
+You can also start from `Project Settings`: click `Share` in the `Feature store sharing` section, select `One feature group, entirely or some of its features`, and pick the feature group.
+
 ### Step 2: Share the feature group
 
-Click `Share` to open the sharing dialog. You can share with either a project or an individual user with `Feature store restricted` role.
+You can share with either a project or an individual user with the [Feature store restricted][feature-store-restricted] role.
+Under `Features to share`, all features are selected; clear the ones the target should not read.
+The primary key and the event time are always shared, because the target needs them to join the feature group and to make point-in-time correct reads.
 
 === "Share with a project"
 
-    Select `Share with Project`, choose the target project, and select which features to share using `Select the features to share`.
+    Click `Share`, select the target project in `With a project`, choose the features, and click `Share`.
 
     <p align="center">
       <figure>
-        <img src="../../../../assets/images/guides/project/sharing/share_feature_group_dialog_project.png" alt="Share Feature Group with Project Dialog">
-        <figcaption>Share feature group with project dialog</figcaption>
+        <img src="../../../../assets/images/guides/project/sharing/share_feature_group_dialog_project.png" alt="The share dialog of a feature group with a target project selected and one feature cleared">
+        <figcaption>Share a feature group with a project</figcaption>
       </figure>
     </p>
 
-    After clicking `Share`, the project appears under the `Shared with projects` section.
+    The project appears under `Shared with projects` on the feature group's `Sharing` tab, and in the `Projects` tab of `Project Settings`.
 
     <p align="center">
       <figure>
-        <img src="../../../../assets/images/guides/project/sharing/list_of_projects_feature_group_shared_with.png" alt="List of projects this Feature Group is shared with">
-        <figcaption>List of projects the feature group is shared with</figcaption>
+        <img src="../../../../assets/images/guides/project/sharing/list_of_projects_feature_group_shared_with.png" alt="The Shared with projects card listing one project that can read all features">
+        <figcaption>Projects the feature group is shared with</figcaption>
       </figure>
     </p>
 
 === "Share with a user"
 
-    Select `Share with User`, choose a user with the [Feature store restricted][feature-store-restricted] role, and select which features to share.
+    Click `Grant access`, select the user in `With a user`, choose the features, and click `Share`.
+    The list offers the project members with the [Feature store restricted][feature-store-restricted] role.
 
     <p align="center">
       <figure>
-        <img src="../../../../assets/images/guides/project/sharing/share_feature_group_dialog_user.png" alt="Share Feature Group with User Dialog">
-        <figcaption>Share feature group with user dialog</figcaption>
+        <img src="../../../../assets/images/guides/project/sharing/share_feature_group_dialog_user.png" alt="The share dialog of a feature group with a restricted user selected and one feature cleared">
+        <figcaption>Grant a restricted user access to a feature group</figcaption>
       </figure>
     </p>
 
-    After clicking `Share`, the user appears under the `Users with restricted access` section.
+    The user appears under `Users with restricted access` on the feature group's `Sharing` tab, and in the `Restricted users` tab of `Project Settings`.
 
     <p align="center">
       <figure>
-        <img src="../../../../assets/images/guides/project/sharing/list_of_users_feature_group_shared_with.png" alt="List of users this Feature Group is shared with">
-        <figcaption>List of users the feature group is shared with</figcaption>
+        <img src="../../../../assets/images/guides/project/sharing/list_of_users_feature_group_shared_with.png" alt="The Users with restricted access card listing one user and the features granted to them">
+        <figcaption>Users with restricted access to the feature group</figcaption>
       </figure>
     </p>
 
@@ -167,13 +195,27 @@ Click `Share` to open the sharing dialog. You can share with either a project or
     fg.revoke_restricted_access("restricted_user@example.com")
     ```
 
+## Unsharing
+
+In the `Feature store sharing` section of `Project Settings`, click the trash icon next to what you want to stop sharing:
+
+- Next to a project marked `Entire feature store`, to unshare the entire feature store from that project.
+- Next to a feature group in the `Projects` tab, to unshare that feature group from that project.
+- Next to a feature group in the `Restricted users` tab, to revoke that user's access to it.
+
+Feature views and training data built on the unshared data stop working for the project or user that loses access, so the dialog asks you to type `confirm` first.
+The same trash icons are on a feature group's `Sharing` tab.
+
+From the API, use `fs.unshare`, `fg.unshare` and `fg.revoke_restricted_access` as shown above.
+
 ## Using shared features
 
 Once features have been shared with your project, you can access them through the UI or the API.
 
 ### Using the UI
 
-Navigate to the project that has access to shared features. In the `Feature Groups` section, use the dropdown in the upper right corner to select which feature store to view.
+Navigate to the project that has access to shared features.
+In the `Feature Groups` section, use the dropdown in the upper right corner to select which feature store to view.
 
 <p align="center">
   <figure>