[Collections] Add collections to collections by slug id (#3551)

* make it more explicit that collections can be added to a collection

* docstring

Author: hanouticelina

src/huggingface_hub/hf_api.py

@@ -8352,10 +8352,10 @@ def add_collection_item(
             collection_slug (`str`):
                 Slug of the collection to update. Example: `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`.
             item_id (`str`):
-                ID of the item to add to the collection. It can be the ID of a repo on the Hub (e.g. `"facebook/bart-large-mnli"`)
-                or a paper id (e.g. `"2307.09288"`).
+                Id of the item to add to the collection. Use the repo_id for repos/spaces/datasets,
+                the paper id for papers, or the slug of another collection (e.g. `"moonshotai/kimi-k2"`).
             item_type (`str`):
-                Type of the item to add. Can be one of `"model"`, `"dataset"`, `"space"` or `"paper"`.
+                Type of the item to add. Can be one of `"model"`, `"dataset"`, `"space"`, `"paper"` or `"collection"`.
             note (`str`, *optional*):
                 A note to attach to the item in the collection. The maximum size for a note is 500 characters.
             exists_ok (`bool`, *optional*):

tests/test_hf_api.py

@@ -4020,15 +4020,17 @@ def test_collection_items(self) -> None:
         # Create some repos
         model_id = self._api.create_repo(repo_name()).repo_id
         dataset_id = self._api.create_repo(repo_name(), repo_type="dataset").repo_id
+        collection_id = self._api.create_collection("nested collection", exists_ok=True).slug
 
         # Create collection + add items to it
         collection = self._api.create_collection(self.title)
         self._api.add_collection_item(collection.slug, model_id, "model", note="This is my model")
         self._api.add_collection_item(collection.slug, dataset_id, "dataset")  # note is optional
+        self._api.add_collection_item(collection.slug, collection_id, "collection")
 
         # Check consistency
         collection = self._api.get_collection(collection.slug)
-        self.assertEqual(len(collection.items), 2)
+        self.assertEqual(len(collection.items), 3)
         self.assertEqual(collection.items[0].item_id, model_id)
         self.assertEqual(collection.items[0].item_type, "model")
         self.assertEqual(collection.items[0].note, "This is my model")
@@ -4037,6 +4039,9 @@ def test_collection_items(self) -> None:
         self.assertEqual(collection.items[1].item_type, "dataset")
         self.assertIsNone(collection.items[1].note)
 
+        self.assertEqual(collection.items[2].item_id, collection_id)
+        self.assertEqual(collection.items[2].item_type, "collection")
+
         # Add existing item fails (except if ignore error)
         with self.assertRaises(HfHubHTTPError):
             self._api.add_collection_item(collection.slug, model_id, "model")
@@ -4063,7 +4068,7 @@ def test_collection_items(self) -> None:
 
         # Check consistency
         collection = self._api.get_collection(collection.slug)
-        self.assertEqual(len(collection.items), 1)  # only 1 item remaining
+        self.assertEqual(len(collection.items), 2)  # only 1 item remaining
         self.assertEqual(collection.items[0].item_id, dataset_id)  # position got updated
 
         # Delete everything