api: better formatting, added links, and examples

per #463 (comment)

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

@@ -1,6 +1,6 @@
 # dvc.api.get_url()
 
-Returns an url of an artifact.
+Returns the URL of a <abbr>data artifact</abbr>.
 
 ## Signature
 
@@ -10,11 +10,22 @@ get_url(path, repo=None, rev=None, remote=None)
 
 ## Parameters
 
-- `path` - a path to an artifact, relative to repo root
+- `path` - path to the target artifact relative to the repository's root
 
-- `repo` - a path or git url of a repo
+- `repo` - path or Git URL of a DVC repository
 
-- `rev` - revision, i.e. a branch, a tag, a SHA. This only works with an url in
-  repo
+- `rev` -
+  [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` - a name of a remote to fetch artifact from/give url to
+- `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

@@ -1,14 +1,21 @@
 # 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!
+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.
 
 > 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.
 
+Import the API with:
+
+```py
+import dvc.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

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

@@ -1,6 +1,9 @@
 # dvc.api.open()
 
-Opens an artifact as a file. May only be used as context manager.
+Opens a <abbr>data 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
 
@@ -10,25 +13,46 @@ open(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
 
 ## Parameters
 
-- `path` - a path to an artifact, relative to repo root
+- `path` - path to the target artifact relative to the repository's root
 
-- `repo` - a path or git url of a repo
+- `repo` - path or Git URL of a DVC repository
 
-- `rev` - revision, i.e. a branch, a tag, a SHA. This only works with an url in
-  repo
+- `rev` -
+  [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` - a name of a remote to fetch artifact from/give url to
+- `remote` - (optional) name of the [DVC remote](/doc/command-reference/remote)
+  to fetch the target artifact from
 
-- `mode` - Mirrors their namesake builtin `open()` has.
+- `mode` - (optional) mirrors the namesake parameter in builtin
+  [`open()`](https://docs.python.org/3.7/library/functions.html#open). Defaults
+  to "r" (read).
 
-- `encoding` - an encoding used to decode contents to a string. Mirrors their
-  namesake builtin `open()` has.
+- `encoding` - (optional) used to decode contents to a string. Mirrors the
+  namesake parameter in builtin `open()`.
 
 ## Example: `open` as a context manager
 
+> See
+> [PEP 343 -- The "with" Statement](https://www.python.org/dev/peps/pep-0343/)
+
+From a DVC remote:
+
 ```py
 with dvc.api.open("path/to/data.csv", remote="my-s3", encoding="utf-8") as f:
     for line in f:
         process(line)
-    ...
+```
+
+From a DVC repository:
+
+```py
+import csv
+import dvc.api
+
+with dvc.api.open("dataset.csv", 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

@@ -1,6 +1,7 @@
 # dvc.api.read()
 
-Returns the contents of an artifact as a bytes object or a string.
+Returns the contents of a <abbr>data artifact</abbr> as a bytes object or as a
+string.
 
 ## Signature
 
@@ -10,16 +11,32 @@ read(path, repo=None, rev=None, remote=None, mode="r", encoding=None)
 
 ## Parameters
 
-- `path` - a path to an artifact, relative to repo root
+- `path` - path to the target artifact relative to the repository's root
 
-- `repo` - a path or git url of a repo
+- `repo` - path or Git URL of a DVC repository
 
-- `rev` - revision, i.e. a branch, a tag, a SHA. This only works with an url in
-  repo
+- `rev` -
+  [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` - a name of a remote to fetch artifact from/give url to
+- `remote` - (optional) name of the [DVC remote](/doc/command-reference/remote)
+  to fetch the target artifact from
 
-- `mode` - Mirrors their namesake builtin `open()` has.
+- `mode` - (optional) mirrors the namesake parameter in builtin
+  [`open()`](https://docs.python.org/3.7/library/functions.html#open). Defaults
+  to "r" (read).
 
-- `encoding` - an encoding used to decode contents to a string. Mirrors their
-  namesake builtin `open()` has.
+- `encoding` - (optional) used to decode contents to a string. Mirrors the
+  namesake parameter in builtin `open()`.
+
+## Example: loading from content
+
+```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

@@ -18,11 +18,14 @@ def summon(
 
 - `name` - object to summon
 
-- `repo` - a path or git url of a repo
+- `repo` - path or Git URL of a DVC repository
 
-- `rev` - revision, i.e. a branch, a tag, a SHA. This only works with an url in
-  repo
+- `rev` -
+  [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` - DVC summon configuration file
+- `summon_file` - summon file describing the object in question. Defaults to
+  `dvcsummon.yaml`.
 
-- `args` - other arguments
+- `args` - arguments to pass onto the object, if any