api: create docs

public/static/docs/api-reference/get_url.md

@@ -0,0 +1,32 @@
+# dvc.api.get_url()
+
+Returns the full URL to the <abbr>data artifact</abbr> specified by its `path`
+in a `repo`.
+
+## Signature
+
+```py
+get_url(path, repo=None, rev=None, remote=None)
+```
+
+## Parameters
+
+- `path` - path to the target artifact relative to the repository's root
+
+- `repo` - path or Git URL of a DVC repository
+
+- `rev` - (optional)
+  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+  (such as a branch name, a tag, or a commit hash). This only works with `repo`
+  URLs.
+
+- `remote` - (optional) name of the [DVC remote](/doc/command-reference/remote)
+  to fetch the target artifact from
+
+## Example
+
+```py
+import dvc.api
+
+resource_url = dvc.api.get_url("data/prepared.tsv", repo="https://github.com/my-org/my-repo.git", remote="my-s3")
+```

public/static/docs/api-reference/index.md

@@ -0,0 +1,28 @@
+# Python API
+
+When you [install](/doc/install) DVC with an environment manager like `pip` or
+`conda`, the `dvc` package becomes available to the corresponding `python`
+interpreter. While most of the package implements our
+[command-line tool](/doc/command-reference), we wrote the `dvc.api` module to
+expose special functions you can use in your Python source code.
+
+> We **strongly** recommend having `dvc` in requirements or setup file for your
+> Python project, and installing it via and env manager such as `pip`.
+
+To import the API, use:
+
+```py
+import dvc.api
+```
+
+This reference provides the details about our API functions, their purpose,
+usage, and examples. Please note that they also have inline documentation, which
+you can see in the module's
+[source code](https://github.com/iterative/dvc/blob/master/dvc/api.py).
+
+> Please don't hesitate in sending a feature request
+> [on GitHub](https://github.com/iterative/dvc.org/issues) with ideas of other
+> functions we could add to the Python API.
+
+Please choose from the navigation sidebar to the left, or click the `Next`
+button below ↘

public/static/docs/api-reference/open.md

@@ -0,0 +1,58 @@
+# dvc.api.open()
+
+Opens a file <abbr>artifact</abbr> as a
+[file object](https://docs.python.org/3.7/glossary.html#term-file-object). May
+only be used as
+[context manager](https://www.python.org/dev/peps/pep-0343/#context-managers-in-the-standard-library).
+
+## Signature
+
+```py
+open(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
+```
+
+## Parameters
+
+- `path` -
+  [path](https://docs.python.org/3.7/glossary.html#term-path-like-object) to the
+  target artifact relative to the repository's root
+
+- `repo` - path or Git URL of a DVC repository
+
+- `rev` - (optional)
+  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+  (such as a branch name, a tag, or a commit hash). This only works with `repo`
+  URLs.
+
+- `remote` - (optional) name of the [DVC remote](/doc/command-reference/remote)
+  to fetch the target artifact from
+
+- `mode` - (optional) mirrors the namesake parameter in builtin
+  [`open()`](https://docs.python.org/3.7/library/functions.html#open). Defaults
+  to `"r"` (read).
+
+- `encoding` - (optional) used to decode contents to a string. Mirrors the
+  namesake parameter in builtin `open()`.
+
+## Example: open from a DVC remote
+
+> See
+> [PEP 343 -- The "with" Statement](https://www.python.org/dev/peps/pep-0343/)
+
+```py
+with dvc.api.open("data/raw.csv", remote="my-s3", encoding="utf-8") as f:
+    for line in f:
+        process(line)
+```
+
+## Example: open from a DVC repository
+
+```py
+import csv
+import dvc.api
+
+with dvc.api.open("dataset/", repo="https://github.com/my-org/my-repo.git") as f:
+    reader = csv.reader(f)
+    for row in reader:
+        # ...
+```

public/static/docs/api-reference/read.md

@@ -0,0 +1,49 @@
+# dvc.api.read()
+
+Returns the contents of a file <abbr>artifact</abbr> as a bytes object or as a
+string.
+
+> Wrapper for [`dvc.api.open()`](/doc/api-reference/open) that returns the
+> results of the file object's
+> [`read()`](https://docs.python.org/3.7/tutorial/inputoutput.html#methods-of-file-objects)
+> method.
+
+## Signature
+
+```py
+read(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
+```
+
+## Parameters
+
+- `path` -
+  [path](https://docs.python.org/3.7/glossary.html#term-path-like-object) to the
+  target artifact relative to the repository's root
+
+- `repo` - path or Git URL of a DVC repository
+
+- `rev` - (optional)
+  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+  (such as a branch name, a tag, or a commit hash). This only works with `repo`
+  URLs.
+
+- `remote` - (optional) name of the [DVC remote](/doc/command-reference/remote)
+  to fetch the target artifact from
+
+- `mode` - (optional) mirrors the namesake parameter in builtin
+  [`open()`](https://docs.python.org/3.7/library/functions.html#open). Defaults
+  to `"r"` (read).
+
+- `encoding` - (optional) used to decode contents to a string. Mirrors the
+  namesake parameter in builtin `open()`.
+
+## Example
+
+```py
+import pickle
+import dvc.api
+
+model = pickle.loads(
+  dvc.api.read("model.pkl", repo="https://github.com/my-org/my-repo.git")
+)
+```

public/static/docs/api-reference/summon.md

@@ -0,0 +1,31 @@
+# dvc.api.summon()
+
+Instantiate an object, described in a _summon file_.
+
+## Signature
+
+```py
+def summon(
+  name,
+  repo=None,
+  rev=None,
+  summon_file="dvcsummon.yaml",
+  args=None
+)
+```
+
+## Parameters
+
+- `name` - object to summon
+
+- `repo` - path or Git URL of a DVC repository
+
+- `rev` - (optional)
+  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+  (such as a branch name, a tag, or a commit hash). This only works with `repo`
+  URLs.
+
+- `summon_file` - YAML file describing the object in question. Defaults to
+  `dvcsummon.yaml`.
+
+- `args` - arguments to pass onto the object, if any

public/static/docs/sidebar.json

@@ -354,6 +354,29 @@
       }
     ]
   },
+  {
+    "slug": "api-reference",
+    "label": "Python API Reference",
+    "source": "api-reference/index.md",
+    "children": [
+      {
+        "slug": "get_url",
+        "label": "get_url()"
+      },
+      {
+        "slug": "open",
+        "label": "open()"
+      },
+      {
+        "slug": "read",
+        "label": "read()"
+      },
+      {
+        "slug": "summon",
+        "label": "summon()"
+      }
+    ]
+  },
   {
     "slug": "understanding-dvc",
     "label": "Understanding DVC",