Skip to content
This repository has been archived by the owner on Oct 16, 2024. It is now read-only.

Content for /docs #43

Merged
merged 129 commits into from
May 24, 2022
Merged

Content for /docs #43

merged 129 commits into from
May 24, 2022

Conversation

mike0sv
Copy link
Contributor

@mike0sv mike0sv commented Apr 14, 2022

related to #28

Review app docs @ https://mlemai-docscontent.gtsb.io/

@rogermparent rogermparent mentioned this pull request Apr 23, 2022
@mike0sv

This comment was marked as resolved.

@rogermparent rogermparent changed the base branch from main to docs-engine April 29, 2022 20:39
@rogermparent rogermparent changed the base branch from docs-engine to main April 29, 2022 20:39
@rogermparent rogermparent reopened this Apr 29, 2022
@rogermparent

This comment was marked as outdated.

@jorgeorpinel
Copy link
Contributor

p.p.s. just assigned us for visibility in https://github.com/orgs/iterative/projects/335. Sorry for noise!

the path argument. This creates a `.mlem` directory and an empty `config.yaml`
file inside it.

Although we recommend using MLEM within a Git repository to track changes using
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mention and link project structure page somewhere here


## Description

The `init` command (without given `path`) defaults to the current directory for
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mention that is does nothing if dir exists

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May not be necessary, it's kind of intuitive?

remote repository (e.g. GitHub).

This command also supports additional options, allowing filtering of MLEM
Objects by type, producing JSON output, selectively displaying
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add examples of those?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also, --no-links is not about selectively displaying links, but the opposite, excluding links from result

usage: mlem create [options] object_type [subtype] path

arguments:
OBJECT_TYPE Type of metafile to create [required]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add possible values?

Copy link
Contributor

@jorgeorpinel jorgeorpinel May 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. We should document the option details in the Options section (for all commands).

Multiple iterations on every section are still needed probably. Get Started and Use Cases should be the priority probably (based on DVC.org traffic/experience).


## Options

- `-c, --conf TEXT`: Values for object fields in format
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mention that there can multiple values (here and in other similar places)

allows us to easily make requests (inference and others) against the served
model.

For the common `fastapi` server implementation, the OpenAPI spec is available on
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

probably too specific. should go to fastapi implementation docs

usage: mlem types [options] [abc] [sub_type]

arguments:
[ABC] Subtype to list implementations. List subtypes if not provided
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

choices?

# types

List different implementations available for a particular MLEM type. If a
subtype is not provided, list all available MLEM types.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it can also show fields for particular implementation

specify: absolute or relative. [default: relative]
- `-h, --help`: Show this message and exit.

## Examples
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add one with rev?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CLI help output examples vs. docs examples deserves it's own epic probably...

Cloning a [MLEM Object](/doc/user-guide/basic-concepts#mlem-objects) from source
to target destination creates an independent copy of the original object. This
can be useful in cases where you need the model without cloning the whole
repository.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or cache remote model locally for further usage

@mike0sv
Copy link
Contributor Author

mike0sv commented May 27, 2022

A bit late, but we used generate_sidebar.py to generate sidebar (duh). It's just easier to use than manually edit json file. We can probably move it from content/ and make more general, but I think it should return :) @jorgeorpinel

@@ -0,0 +1,29 @@
# mlem.api.init()

Creates `.mlem/` directory in `path`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to use term "MLEM project" somwhere here.

Also, since a lot of our CLI are just wrappers around API, we should probably use the same descriptions for both.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same goes for their arguments/options (if they are the same of course from cli/api)

path: str,
repo: Optional[str] = None,
sample_data=None,
fs: Union[str, AbstractFileSystem] = None,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


## Exceptions

- `MlemObjectNotFound` - Thrown if we can't find MLEM object
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But we are saving new object....
If it can be thrown, need better explanation in which cases


## Exceptions

None
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably here we can actually not find the object :) or project

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same for load_meta

```py
from mlem.api import init

init(path)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add multiple examples with explanations like

init()  # init in current directory
init("s3://bucket")  # init in cloud
etc

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, this looks like examples actually. Let me check dvc docs to see what is the difference

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jorgeorpinel What is the purpose of usage section? We can see signature above and some examples in the end. For DVC python API usage has the same content as one of the examples in most cases

train = DataFrame(train)
train.columns = train.columns.astype(str)
model = DecisionTreeClassifier().fit(train, target)
path = os.path.join(os.getcwd(), "saved-model")
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dont think we need this, just use string directly


- `MlemObjectNotFound` - Thrown if we can't find MLEM object

## Example: Save a trained model with MLEM
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example with cloud save?

import os
from mlem.api import load

out_path = os.path.join(os.getcwd(), "saved-model")
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not needed?

```py
from mlem.api import ls

objects = ls(".", rev=None, type_filter=None, include_links=True)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's strange to set default values. Better to have more examples where those values are not default (with explanation what it will do and where)

- `target` (optional) - Path to save MLEM object into.
- `target_repo` (optional) - Path to MLEM repo for `target`.
- `target_fs` (optional) - FileSystem for the `target` argument
- `type_` (optional) - Specify how to read file. Available types: ['pickle',
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need to mention import modifiers (like pandas[csv]). Maybe not here, but in user guide. But probably on both pages

```py
from mlem.api import clone

cloned_obj = clone(path="rf", target="mymodel". repo="https://github.com/iterative/example-mlem-get-started", rev="main", target_repo="s3://mybucket/mymodel", load_value=True)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

,

interface = ModelInterface.from_model(m)

server_obj = FastAPIServer().app_init(interface)
serve(m, server_obj)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

server_obj should be just FastAPIServer() or "fastapi"

@aguschin aguschin mentioned this pull request May 30, 2022
@jorgeorpinel jorgeorpinel mentioned this pull request Oct 10, 2022
8 tasks
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants