From 21d0c9eb041741fd5c5b6c513da5aebdd199aa3c Mon Sep 17 00:00:00 2001
From: Tuan Tran <tuantran@devfair0436.h2.fair>
Date: Sun, 10 Dec 2023 00:50:50 -0800
Subject: [PATCH] update docstring and fair loader behaviour

---
 doc/index.rst                |  1 +
 doc/reference/asset.rst      | 20 ++++++++++++++++++++
 src/fairseq2/assets/store.py |  4 ++++
 3 files changed, 25 insertions(+)
 create mode 100644 doc/reference/asset.rst

diff --git a/doc/index.rst b/doc/index.rst
index 87a820250..d916ef9ae 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,6 +13,7 @@ other content generation tasks.
    :maxdepth: 1
 
    reference/data
+   reference/asset
    reference/all
 
 .. toctree::
diff --git a/doc/reference/asset.rst b/doc/reference/asset.rst
new file mode 100644
index 000000000..9b55d95a0
--- /dev/null
+++ b/doc/reference/asset.rst
@@ -0,0 +1,20 @@
+fairseq2.asset
+=============
+.. body
+
+.. currentmodule:: fairseq2.asset
+
+    ``fairseq2.asset`` provides API to load the different model using the "model cards" from different "stores".
+
+    A model card is a .YAML file that contains information about a model and instructs a 
+    :pc:class:`fairseq2.models.utils.generic_loaders.ModelLoader` on how to load the model into the memory.
+    A store is a place where all the model cards are stored. By default, fairseq2 will look up the following stores:
+
+    * System asset store: Cards that are shared by all users. By default, the system store is `/etc/fairseq2/assets`,
+    but this can be changed via the environment variable `FAIRSEQ2_ASSET_DIR`
+    * User asset store: Cards that are only available to the user. By default, the user store is 
+    `~/.config/fairseq2/assets`, but this can be changed via the environment variable `FAIRSEQ2_USER_ASSET_DIR`
+    * (Internal only) Meta asset store: For Meta employees' convenience, we set up a central store that contains
+    model cards with e.g intermediate checkpoints, extra internal information etc. This store is registered automatically
+    when one logs into the Fair cluster. If you wish not to use this central store, set the environment variable 
+    `NO_FAIR_CARD=ON`
\ No newline at end of file
diff --git a/src/fairseq2/assets/store.py b/src/fairseq2/assets/store.py
index a4f142382..fd9f22daa 100644
--- a/src/fairseq2/assets/store.py
+++ b/src/fairseq2/assets/store.py
@@ -216,6 +216,10 @@ def _load_faircluster() -> None:
     if "FAIR_ENV_CLUSTER" not in os.environ:
         return
 
+    # Disable the central Fair model store i.e. for debugging
+    if os.getenv("NO_FAIR_CARD", None):
+        return
+
     asset_store.env_resolvers.append(lambda: "faircluster")
 
     # This directory is meant to store cluster-wide asset cards.