token annotation examples added to docs

content/docs/guide-development.md

@@ -122,6 +122,37 @@ if credentials_env:
 
 ``` 
 
+### Adding token annotations
+
+In case your notebook uses token to access some resources this should be reflected in the annotations in the notebook cell tagged `parameters` in the following way:
+
+```
+# oda:oda_token_access oda:InOdaContext .
+``` 
+The above expression enables the standard mechanism to supply token using oda context variable. Then the token can be accessed from the code in the following way:
+
+```
+from oda_api.api import get_context
+token = get_context()['token']
+```  
+However, we recommend instead using higer level  `oda_api.token` API, which also provides token validation and token discovery method as options. The code above is eqivalent to the following higher level code
+
+```
+from oda_api.token import discover_token, TokenLocation
+token = discover_token(allow_invalid=True)
+```  
+Below is the entire list of token locations supported in order of priority.
+
+```
+class TokenLocation(Enum):
+    ODA_ENV_VAR = "environment variable ODA_TOKEN"
+    FILE_CUR_DIR = ".oda-token file in current directory"
+    FILE_HOME = ".oda-token file in home"
+    CONTEXT_FILE = "context file current directory"
+```
+
+By default, token validation is enabled and the attempts are made to load the token from all the supported locations in the order they appear in the TokenLocation class. Note that token locations other than `TokenLocation.CONTEXT_FILE` are useful to test the notebook or run it iteratively, but they don't have any corresponding annotations in the ontology.
+
 ### How to annotate the notebook outputs
 
 A cell tagged "outputs" defines the data product(s) that will be provided by the service: