📝 update docstrings for create_model

timm/models/_factory.py

@@ -46,27 +46,59 @@ def create_model(
         no_jit: Optional[bool] = None,
         **kwargs,
 ):
-    """Create a model
+    """Create a model.
 
     Lookup model's entrypoint function and pass relevant args to create a new model.
 
-    **kwargs will be passed through entrypoint fn to timm.models.build_model_with_cfg()
+    <Tip>
+        **kwargs will be passed through entrypoint fn to ``timm.models.build_model_with_cfg()``
         and then the model class __init__(). kwargs values set to None are pruned before passing.
+    </Tip>
 
     Args:
-        model_name (str): name of model to instantiate
+        model_name (str):
-        pretrained (bool): load pretrained ImageNet-1k weights if true
+            Name of model to instantiate.
-        pretrained_cfg (Union[str, dict, PretrainedCfg]): pass in external pretrained_cfg for model
+        pretrained (`bool`, *optional*, defaults to `False`):
-        pretrained_cfg_overlay (dict): replace key-values in base pretrained_cfg with these
+            If set to `True`, load pretrained ImageNet-1k weights.
-        checkpoint_path (str): path of checkpoint to load _after_ the model is initialized
+        pretrained_cfg (Union[str, dict, PretrainedCfg], *optional*):
-        scriptable (bool): set layer config so that model is jit scriptable (not working for all models yet)
+            Pass in an external pretrained_cfg for model.
-        exportable (bool): set layer config so that model is traceable / ONNX exportable (not fully impl/obeyed yet)
+        pretrained_cfg_overlay (dict, *optional*):
-        no_jit (bool): set layer config so that model doesn't utilize jit scripted layers (so far activations only)
+            Replace key-values in base pretrained_cfg with these.
-
+        checkpoint_path (str, *optional*):
-    Keyword Args:
+            Path of checkpoint to load _after_ the model is initialized.
-        drop_rate (float): dropout rate for training (default: 0.0)
+        scriptable (bool, *optional*):
-        global_pool (str): global pool type (default: 'avg')
+            Set layer config so that model is jit scriptable (not working for all models yet).
-        **: other kwargs are consumed by builder or model __init__()
+        exportable (bool, *optional*):
+            Set layer config so that model is traceable / ONNX exportable (not fully impl/obeyed yet).
+        no_jit (bool, *optional*):
+            Set layer config so that model doesn't utilize jit scripted layers (so far activations only).
+
+    **Keyword Args**:
+
+        - **drop_rate** (float, *optional*, defaults to `0.0`):
+            Dropout rate for training.
+        - **global_pool** (str, *optional*, defaults to `'avg'`):
+            Global pooling type.
+        - All other kwargs are consumed by builder or model ``__init__()``.
+
+    Example:
+
+    ```py
+    >>> from timm import create_model
+
+    >>> # Create a MobileNetV3-Large model with no pretrained weights.
+    >>> model = create_model('mobilenetv3_large_100')
+
+    >>> # Create a MobileNetV3-Large model with pretrained weights.
+    >>> model = create_model('mobilenetv3_large_100', pretrained=True)
+    >>> model.num_classes
+    1000
+
+    >>> # Create a MobileNetV3-Large model with pretrained weights and a new head with 10 classes.
+    >>> model = create_model('mobilenetv3_large_100', pretrained=True, num_classes=10)
+    >>> model.num_classes
+    10
+    ```
     """
     # Parameters that aren't supported by all models or are intended to only override model defaults if set
     # should default to None in command line args/cfg. Remove them if they are present and not set so that