api: create documentation

[jorgeorpinel]

See src @ https://github.com/iterative/dvc/blob/master/dvc/api.py

dvc.api.get_url
dvc.api.open
dvc.api.read

Please more insights here More details in #463 (comment).

Also, please update the one mention to API in the data registry (which will me merged with #818) per #818 (comment).

UPDATE:

• Also (at least basic docs for) dvc.api.summon and open another issue to complete it later.
• And try to do app: automatic links for API function names in md automatic links for API function names (to api ref) #910 once api: create docs #908 is merged.

[shcheklein]

@Suor can you describe it briefly, please :)

[dnabanita7]

@jorgeorpinel @shcheklein can you please explain this a bit more. I would like to take this up.

[shcheklein]

@Suor ? can you give a summary or is there a link? we should probably put docstrings around APIs before we release it.

[dnabanita7]

Sorry, I am unable to search dvc.api.get_content . Do you mean get_url or __getattr__ ?
dvc.api.open and other methods already have docstrings around them in iterative/dvc/dvc/api,py

[shcheklein]

@naba7 it's read now, I believe. There are only three public methods in dvc.api. Those should be described. And let's create a ticket on iterative/dvc to update docstrings for those APIs.

[Suor]

They have some short docstrings, I will update them based on future docs or discussion here if we decide to do that.

So, what is this about? There are three public things in dvc.api now:

1. read(path, repo=None, rev=None, remote=None, mode="r", encoding=None) - returns the contents of an artifact as a bytes object or a string.
2. get_url(path, repo=None, rev=None, remote=None) - returns an url of an artifact.
3. open(path, repo=None, rev=None, remote=None, mode="r", encoding=None) - opens an artifact as a file, may only be used as context manager:

   with dvc.api.open("path/to/data.csv", remote="my-s3", encoding="utf-8") as f:
       for line in f:
           process(line)

Arguments always mean the same:

path - a path to an artifact, relative to repo root,
repo - a path or git url of a repo,
rev - revision, i.e. a branch, a tag, a sha. This only works with an url in repo,
remote - a name of a remote to fetch artifact from/give url to
mode - a mode with which we open a file, the only sensible options are r/rt and rb
encoding - an encoding used to decode contents to a string

mode and encoding mirror their namesakes builtin open() has.

[shcheklein]

k, thanks @Suor. @naba7 now we need to come with a good place and a format for it. Probably, we need a separate top-level section. API reference similar to command reference we have.

[dnabanita7]

Shall we describe read, open, and get_url in different sections inside API Reference?
We can have another section for describing path, repo, rev, remote, mode, encoding.

[shcheklein]

@naba7 yes, it should be a separate section per call. At least for now.

path, repo, rev, remote, mode, encoding - are not APIs. repo is, but it's not officially released yet.

Can you take a look for some good projects that have APIs documented to come up with a good page template for this?

[dnabanita7]

How about this format angularJS or microsoft or Azure?

We can use these formats and write a introductory page listing all the APIs and linking them to GitHub

[jorgeorpinel]

@Suor are repo=None, rev=None, remote=None default values actually None? Or do they get turned into repo='.', rev='HEAD', remote=(read from config file)? Probably important to document (both in docstring and) in the API ref.

@shcheklein re

Probably, we need a separate top-level section. API reference similar to command reference we have.

Agree, perhaps in docs path /api-reference and the index page for that section could explain what is the API and how to start using it. Actually its not that obvious! I'm not 100% sure what we mean by "the DVC API" for example. Is it a Python library people can install separately?

$ pip install dvc
...
$ python
...
>>> from dvc import api as dvcapi
>>> dvcapi
<module 'dvc.api' from '/.../dvc/dvc/api.py'>
>>> # etc