api: create docs

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

@@ -0,0 +1,20 @@
+# dvc.api.get_url()
+
+Returns an url of an artifact.
+
+## Signature
+
+```py
+get_url(path, repo=None, rev=None, remote=None)
+```
+
+## Parameters
+
+- `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

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

@@ -0,0 +1,18 @@
+# Python API
+
+When you [install](/doc/install) DVC in an environment, the `dvc` package
+becomes available for usage in Python source code. While most of its code is the
+internal implementation of the `dvc` command-line tool, we wrote the `dvc.api`
+module to expose special user functions that we hope you may find useful!
+
+> 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.
+
+This reference provides the details about our API functions, their purpose,
+usage, and examples. Please note that they also have internal documentation
+which you can see in the module's
+[source code](https://github.com/iterative/dvc/blob/master/dvc/api.py).
+
+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,34 @@
+# dvc.api.open()
+
+Opens an artifact as a file. May only be used as context manager.
+
+## Signature
+
+```py
+open(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
+```
+
+## Parameters
+
+- `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` - Mirrors their namesake builtin `open()` has.
+
+- `encoding` - an encoding used to decode contents to a string. Mirrors their
+  namesake builtin `open()` has.
+
+## Example: `open` as a context manager
+
+```py
+with dvc.api.open("path/to/data.csv", remote="my-s3", encoding="utf-8") as f:
+    for line in f:
+        process(line)
+    ...
+```

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

@@ -0,0 +1,25 @@
+# dvc.api.read()
+
+Returns the contents of an artifact as a bytes object or a string.
+
+## Signature
+
+```py
+read(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
+```
+
+## Parameters
+
+- `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` - Mirrors their namesake builtin `open()` has.
+
+- `encoding` - an encoding used to decode contents to a string. Mirrors their
+  namesake builtin `open()` has.

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

@@ -0,0 +1,28 @@
+# dvc.api.summon()
+
+Instantiate an object described in the summon file.
+
+## Signature
+
+```py
+def summon(
+  name,
+  repo=None,
+  rev=None,
+  summon_file="dvcsummon.yaml",
+  args=None
+)
+```
+
+## Parameters
+
+- `name` - object to summon
+
+- `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
+
+- `summon_file` - DVC summon configuration file
+
+- `args` - other arguments

public/static/docs/sidebar.json

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