Merge pull request #197 from iterative/api-reference-script

Api reference script

Author: aguschin

content/docs/api-reference/apply.md

@@ -1,6 +1,6 @@
 # mlem.api.apply()
 
-Apply provided model against provided data
+Apply provided model against provided data.
 
 ```py
 def apply(
@@ -9,8 +9,6 @@ def apply(
     method: str = None,
     output: str = None,
     target_project: str = None,
-    index: bool = None,
-    external: bool = None,
     batch_size: Optional[int] = None,
 ) -> Optional[Any]
 ```
@@ -33,16 +31,19 @@ required.
 
 ## Parameters
 
-- **`model`** (required) - MLEM model (a MlemModel object).
+- **`model`** (required) - MLEM model.
 - **`data`** (required) - Input to the model.
-- `method` (optional) - Which model method to use. If None, use the only method
-  model has. If more than one is available, will fail.
-- `output` (optional) - If value is provided, assume its path and save output
+- `method` (optional) - Which model method to use.If None, use the only method
+  model has.If more than one is available, will fail.
+- `output` (optional) - If value is provided,assume it's path and save output
   there.
-- `target_project` (optional) - The path to project to save the results to.
-- `index` (optional) - Whether to index saved output in MLEM root folder.
-- `external` (optional) - Whether to save result outside mlem dir.
-- `batch_size` (optional) - If data is to be loaded and applied in batches.
+- `target_project` (optional) - Path to MLEM project to save the result to.
+- `batch_size` (optional) - If provided, will process data in batches of given
+  size.
+
+## Returns
+
+If `output=None`, returns results for given data. Otherwise returns None.
 
 ## Exceptions
 

content/docs/api-reference/apply_remote.md

@@ -1,6 +1,6 @@
 # mlem.api.apply_remote()
 
-Apply deployed model (possibly remote) against provided data.
+Apply provided model against provided data.
 
 ```py
 def apply_remote(
@@ -9,7 +9,6 @@ def apply_remote(
     method: str = None,
     output: str = None,
     target_project: str = None,
-    index: bool = False,
     **client_kwargs,
 ) -> Optional[Any]
 ```
@@ -34,14 +33,16 @@ knows how to make requests to the deployed model.
 
 - **`client`** (required) - The client to access methods of deployed model.
 - **`data`** (required) - Input to the model.
-- `method` (optional) - Which model method to use. If None, use the only method
-  model has. If more than one is available, will fail.
-- `output` (optional) - If value is provided, assume its path and save output
+- **`method`** (required) - Which model method to use.If None, use the only
+  method model has.If more than one is available, will fail.
+- `output` (optional) - If value is provided,assume it's path and save output
   there.
-- `target_project` (optional) - The path to project to save the results to.
-- `index` (optional) - Whether to index saved output in MLEM root folder.
-- `client_kwargs` (optional) - Keyword arguments for the underlying client
-  implementation being used.
+- `target_project` (optional) - Path to MLEM project to save the result to.
+- `**client_kwargs` (optional) - Additional arguments to pass to client.
+
+## Returns
+
+If `output=None`, returns results for given data. Otherwise returns None.
 
 ## Exceptions
 

content/docs/api-reference/build.md

@@ -1,8 +1,7 @@
 # mlem.api.build()
 
-Build a [MLEM model](/doc/object-reference/mlem-abcs#modeltype) in pip-ready
-format, a built package using whl, docker-build-ready folder or directly build a
-docker image.
+Pack model into something useful, such as docker image, Python package or
+something else.
 
 ```py
 def build(
@@ -27,33 +26,56 @@ This API is the underlying mechanism for the
 programmatically create ship-able assets from MlemModels such as pip-ready
 packages, Docker images, etc.
 
-<admon type="tip">
+<details>
 
-The arguments supplied to this method can be found with `mlem types`:
+### The arguments supplied to this method can be found with `mlem types` command
 
 ```cli
 $ mlem types builder pip
+Type mlem.contrib.pip.base.PipBuilder
+MlemABC parent type: builder
+MlemABC type: pip
+MlemObject type name: builder
+Create a directory python package
+Fields:
 [required] package_name: str
+        Name of python package
 [required] target: str
-[not required] templates_dir: str = []
+        Path to save result
+[not required] templates_dir: List[str] = []
+        list of directories to look for jinja templates
+[not required] templates_dir.0: str = None
+        Element of templates_dir
 [not required] python_version: str = None
+        Required python version
 [not required] short_description: str = ""
+        short_description
 [not required] url: str = ""
+        url
 [not required] email: str = ""
+        author's email
 [not required] author: str = ""
+        author's name
 [not required] version: str = "0.0.0"
-[not required] additional_setup_kwargs: typing.Any = {}
+        package version
+[not required] additional_setup_kwargs: Dict[str, any] = {}
+        additional parameters for setup()
+[not required] additional_setup_kwargs.key: any = None
+        Element of additional_setup_kwargs
 ```
 
-</admon>
+</details>
 
 ## Parameters
 
-- **`builder`** (required) - Builder to use. Out-of-the-box supported string
-  values are ['whl', 'pip', 'docker_dir', 'docker'].
+- **`builder`** (required) - Builder to use.
 - **`model`** (required) - The model to build.
-- `builder_kwargs` (optional) - Keyword arguments for the underlying builder
-  being used.
+- **`builder_kwargs`** (required) - Additional keyword arguments to pass to the
+  builder.
+
+## Returns
+
+The result of the build, different for different builders.
 
 ## Exceptions
 

content/docs/api-reference/clone.md

@@ -1,7 +1,7 @@
 # mlem.api.clone()
 
-Clones MLEM object from `path` to `target` and returns Python representation for
-the created object.
+Clones [MLEM Object](/doc/user-guide/basic-concepts) from `path` to `out` and
+returns Python representation for the created object.
 
 ```py
 def clone(
@@ -14,8 +14,6 @@ def clone(
     target_fs: Optional[str] = None,
     follow_links: bool = True,
     load_value: bool = False,
-    index: bool = None,
-    external: bool = None,
 ) -> MlemObject
 ```
 
@@ -37,20 +35,21 @@ target.
 ## Parameters
 
 - **`path`** (required) - Path to the object. Could be local path or path inside
-  a Git repo.
+  a git repo.
 - **`target`** (required) - Path to save the copy of initial object to.
 - `project` (optional) - URL to project if object is located there.
-- `rev` (optional) - revision, could be Git commit SHA, branch name or tag.
+- `rev` (optional) - revision, could be git commit SHA, branch name or tag.
 - `fs` (optional) - filesystem to load object from
 - `target_project` (optional) - path to project to save cloned object to
 - `target_fs` (optional) - target filesystem
-- `follow_links` (optional) - If object we read is a MLEM link, whether to load
-  the actual object link points to. Defaults to True.
-- `load_value` (optional) - Load actual Python object incorporated in MlemMeta
-  object. Defaults to False.
-- `index` (optional) - Whether to index output in .mlem directory
-- `external` (optional) - whether to put object inside mlem dir in target
-  project
+- `follow_links` (optional) - If object we read is a MLEM link, whether to
+  loadthe actual object link points to. Defaults to True.
+- `load_value` (optional) - Load actual python object incorporated in
+  MlemObject. Defaults to False.
+
+## Returns
+
+`MlemObject`: Copy of initial object saved to `out`.
 
 ## Exceptions
 

content/docs/api-reference/deploy.md

@@ -1,29 +1,21 @@
 # mlem.api.deploy()
 
-Deploy a model to target environment. Can use existing deployment declaration or
-create a new one on-the-fly.
+Deploy a model to a target environment. Can use an existing deployment
+declaration or create a new one on-the-fly.
 
 ```py
 def deploy(
-    deploy_meta_or_path: Union[MlemDeploy, str],
-    model: Union[MlemModel, str] = None,
+    deploy_meta_or_path: Union[MlemDeployment, str],
+    model: Union[MlemModel, str],
     env: Union[MlemEnv, str] = None,
     project: Optional[str] = None,
+    rev: Optional[str] = None,
     fs: Optional[AbstractFileSystem] = None,
-    external: bool = None,
-    index: bool = None,
+    env_kwargs: Dict[str, Any] = None,
     **deploy_kwargs,
-) -> MlemDeploy
+) -> MlemDeployment
 ```
 
-[//]: # '### Usage:'
-[//]: #
-[//]: # '```py'
-[//]: # 'from mlem.api import deploy'
-[//]: #
-[//]: # '#TODO'
-[//]: # '```'
-
 ## Description
 
 This API is the underlying mechanism for the
@@ -32,17 +24,18 @@ provides a programmatic way to create deployments for a target environment.
 
 ## Parameters
 
-- **`deploy_meta_or_path`** (required) - Path to deployment meta (will be
-  created if it does not exist)
-- `model` (optional) - Path to model
-- `env` (optional) - Path to target environment
-- `project` (optional) - Path to MLEM project
-- `fs` (optional) - filesystem to load deploy meta from. If not provided, will
-  be inferred from `deploy_meta_or_path`
-- `external` (optional) - Save result not in mlem dir, but directly in project
-- `index` (optional) - Whether to index output in .mlem directory
-- `deploy_kwargs` (optional) - Configuration for new deployment meta if it does
-  not exist
+- **`deploy_meta_or_path`** (required) - MlemDeployment object or path to it.
+- **`model`** (required) - The model to deploy.
+- **`env`** (required) - The environment to deploy to.
+- `project` (optional) - Path to mlem project where to load obj from.
+- `rev` (optional) - Revision if object is stored in git repo.
+- `fs` (optional) - Filesystem to use to load the object.
+- `env_kwargs` (optional) - Additional kwargs to pass to the environment.
+- `deploy_kwargs` (optional) - Additional kwargs to pass to the deployment.
+
+## Returns
+
+`MlemDeployment`: The deployment object.
 
 ## Exceptions
 

content/docs/api-reference/import_object.md

@@ -1,7 +1,7 @@
 # mlem.api.import_object()
 
-Try to load an object as MLEM model (or dataset) and return it, optionally
-saving to the specified target location.
+Try to load an object as MLEM model (or data) and return it, optionally saving
+to the specified target location.
 
 ```py
 def import_object(
@@ -14,8 +14,6 @@ def import_object(
     target_fs: Optional[AbstractFileSystem] = None,
     type_: Optional[str] = None,
     copy_data: bool = True,
-    external: bool = None,
-    index: bool = None,
 )
 ```
 
@@ -47,19 +45,21 @@ command.
 
 ## Parameters
 
-- **`path`** (required) - Path of file to import.
-- `project` (optional) - Path to MLEM project.
-- `rev` (optional) - revision, could be Git commit SHA, branch name or tag.
-- `fs` (optional) - FileSystem for the `path` argument
-- `target` (optional) - Path to save MLEM object into.
-- `target_project` (optional) - Path to MLEM project for `target`.
-- `target_fs` (optional) - FileSystem for the `target` argument
-- `type_` (optional) - Specify how to read file. Available types: ['pickle',
-  'pandas']. Defaults to auto-infer.
-- `copy_data` (optional) - Whether to create a copy of file in target location
-  or just link existing file. Defaults to True.
-- `external` (optional) - Save result directly to `target` (not inside `.mlem/`)
-- `index` (optional) - Whether to index output in `.mlem/` directory
+- **`path`** (required) - Path to the object to import.
+- `project` (optional) - Path to mlem project where to load obj from.
+- `rev` (optional) - Revision if object is stored in git repo.
+- `fs` (optional) - Filesystem to use to load the object.
+- `target` (optional) - Where to store the imported object.
+- `target_project` (optional) - If provided, treat `target` as object name and
+  dumpobject in this MLEM Project.
+- `target_fs` (optional) - Filesystem to use to save the object.
+- `type_` (optional) - Type of the object to import. If not provided, will try
+  toinfer from the object itself.
+- `copy_data` (optional) - Whether to copy data to the target location.
+
+## Returns
+
+`MlemObject`: Imported object.
 
 ## Exceptions
 

content/docs/api-reference/init.md

@@ -1,28 +1,22 @@
 # mlem.api.init()
 
-Creates `.mlem.yaml` config file in `path`. See
-[User Guide](/doc/user-guide/configuration) for more details.
+Creates [MLEM config](/doc/user-guide/configuration) in `path`.
 
 ```py
 def init(path: str = ".") -> None
 ```
 
-### Usage:
-
-```py
-from mlem.api import init
-
-init(path)
-```
-
 ## Description
 
 Initializes a MLEM project by creating a new and empty `.mlem.yaml` file.
 
 ## Parameters
 
-- **`path`** (required) - location of the target where a MLEM project has to be
-  initialized i.e. a `.mlem/` folder has to be created. `.` by default
+- `path` (optional) - Path to create config in. Defaults to current directory.
+
+## Returns
+
+None
 
 ## Exceptions