docs: regular update (early August)

src/Documentation/glossary.js

@@ -5,15 +5,15 @@ export default {
     'relevant DVC concepts and terminologies which are frequently used.',
   contents: [
     {
-      name: 'Workspace directory',
+      name: 'DVC Workspace',
       match: ['workspace'],
       desc:
         'The **workspace** contains all of your DVC **project** files and ' +
         "directories. It's typically also a Git **repository**. See also " +
         '[`dvc init`](/doc/commands-reference/init).'
     },
     {
-      name: 'DVC cache',
+      name: 'DVC Cache',
       match: ['DVC cache', 'cache', 'cache directory'],
       desc:
         'The DVC cache is a hidden storage (by default located in the ' +
@@ -23,7 +23,7 @@ export default {
         '#structure-of-cache-directory).'
     },
     {
-      name: 'Data artifact',
+      name: 'Data Artifact',
       match: ['data artifact', 'data artifacts'],
       desc:
         'Any **data** file or directory, as well as intermediate or final ' +
@@ -32,7 +32,7 @@ export default {
         '(/doc/use-cases/data-and-model-files-versioning) for more details.'
     },
     {
-      name: 'Import stage',
+      name: 'Import Stage',
       match: ['import stage', 'import stages'],
       desc:
         'Stage (DVC-file) created with the `dvc import` or `dvc import-url` ' +

static/docs/commands-reference/add.md

@@ -105,7 +105,7 @@ models). This way you bring data provenance and make your project reproducible.
   location, by including a path in the provided value (e.g.
   `-f stages/stage.dvc`).
 
-## Examples: Single file
+## Example: Single file
 
 Take a file under DVC control:
 
@@ -158,7 +158,7 @@ $ file .dvc/cache/d8/acabbfd4ee51c95da5d7628c7ef74b
 .dvc/cache/d8/acabbfd4ee51c95da5d7628c7ef74b: ASCII text
 ```
 
-## Examples: Directory
+## Example: Directory
 
 What if you have not one dog picture, but hundreds of pictures of dogs and cats?
 Your goal might be to build an algorithm to identify dogs and cats in pictures,

static/docs/commands-reference/cache.md

@@ -35,7 +35,7 @@ config option, for more information on file links on different platforms.)
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Example
+## Examples
 
 The main use of this command is to apply the `-v` and `-q` options to
 `dvc cache dir` which doesn't have them:

static/docs/commands-reference/cache_dir.md

@@ -40,7 +40,7 @@ file location**. They are required in the latter form for the config file.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
-## Examples: Using relative path
+## Example: Using relative path
 
 ```dvc
 $ dvc cache dir ../dir
@@ -54,7 +54,7 @@ $ cat .dvc/config
 `../dir` has been resolved relative to the `.dvc/` dir, resulting in
 `../../dir`.
 
-## Examples: Using absolute path
+## Example: Using absolute path
 
 ```dvc
 $ dvc cache dir /path/to/dir

static/docs/commands-reference/checkout.md

@@ -103,36 +103,20 @@ be pulled from a remote cache using `dvc pull`.
 
 ## Examples
 
-To explore `dvc checkout` let's consider a simple workspace with several
-[stages](/doc/commands-reference/run), and a few Git tags. Then with
-`git checkout` and `dvc checkout` we can see what happens as we shift from tag
-to tag.
+Let's employ a simple workspace with some stages and a few Git tags, such as our
+[get started example repo](https://github.com/iterative/example-get-started).
+Then we can see what happens with `git checkout` and `dvc checkout` as we switch
+from tag to tag.
 
 <details>
 
 ### Click and expand to setup the project
 
-This step is optional, and you can run it only if you want to run this examples
-in your environment. First, you need to download the project:
+Start by cloning our sample repo if you don't already have it:
 
 ```dvc
 $ git clone https://github.com/iterative/example-get-started
-```
-
-Second, let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with
-[virtualenv](https://virtualenv.pypa.io/en/stable/) or a similar tool:
-
-```dvc
 $ cd example-get-started
-$ virtualenv -p python3 .env
-$ source .env/bin/activate
-```
-
-Now, we can install requirements for the project:
-
-```dvc
-$ pip install -r requirements.txt
 ```
 
 </details>
@@ -157,7 +141,6 @@ solving the problem:
 
 ```dvc
 $ git tag
-
 baseline     <- first simple version of the model
 bigram       <- use bigrams to improve the model
 ```

static/docs/commands-reference/commit.md

@@ -90,37 +90,32 @@ into play. It handles that last step of adding the file to the DVC cache.
 
 ## Examples
 
-To explore `dvc commit` let's consider a simple pipeline with several stages:
-the example workspace used in the [Get Started](/doc/get-started) section.
+Let's employ a simple workspace with several stages, such as the DVC project
+created in our [Get Started](/doc/get-started) section. Then we can see what
+happens with `git commit` and `dvc commit` in different situations.
 
 <details>
 
 ### Click and expand to setup the project
 
-This step is optional, and you can run it only if you want to run this examples
-in your environment. First, you need to download the project:
+Start by cloning our sample repo if you don't already have it:
 
 ```dvc
 $ git clone https://github.com/iterative/example-get-started
+$ cd example-get-started
 ```
 
-Second, let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with
-[virtualenv](https://virtualenv.pypa.io/en/stable/) or a similar tool:
+Now let's install the requirements. But before we do that, we **strongly**
+recommend creating a virtual environment with a tool such as
+[virtualenv](https://virtualenv.pypa.io/en/stable/):
 
 ```dvc
-$ cd example-get-started
 $ virtualenv -p python3 .env
 $ source .env/bin/activate
-```
-
-Now, we can install requirements for the project:
-
-```dvc
 $ pip install -r requirements.txt
 ```
 
-Then download the precomputed data using:
+Download the precomputed data using:
 
 ```dvc
 $ dvc pull --all-branches --all-tags
@@ -221,7 +216,7 @@ $ ls .dvc/cache/70
 And we've verified that `dvc commit` has saved the changes into the cache, and
 that the new instance of `model.pkl` is in the cache.
 
-## Example: Running without DVC
+## Example: Running commands without DVC
 
 It is also possible to execute the commands that are executed by `dvc repro` by
 hand. You won't have DVC helping you, but you have the freedom to run any script

static/docs/commands-reference/config.md

@@ -180,7 +180,7 @@ more about the state file that is used for optimization.
   so that when it needs to cleanup the database it could sort them by the
   timestamp and remove the oldest ones. Default quota is set to 50(percent).
 
-## Examples: Core config options
+## Example: Core config options
 
 Set the `dvc` log level to `debug`:
 
@@ -200,7 +200,7 @@ $ dvc remote add myremote s3://bucket/path
 $ dvc config core.remote myremote
 ```
 
-## Examples: Default remotes
+## Example: Default remotes
 
 Use remote `myremote` by default:
 
@@ -227,7 +227,7 @@ which is equivalent to:
 $ dvc config core.remote -u
 ```
 
-## Examples: Cache config options
+## Example: Cache config options
 
 Set the cache directory to an absolute path:
 

static/docs/commands-reference/destroy.md

@@ -31,7 +31,7 @@ DVC repository destruction.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Example
+## Examples
 
 ```dvc
 $ dvc init
@@ -64,9 +64,8 @@ $ dvc cache dir /mnt/cache
 $ dvc add foo
 ```
 
-`dvc cache dir` changed the location of cache storage to exernal
-location. Content of DVC repository:
-
+`dvc cache dir` changed the location of cache storage to exernal location.
+Content of DVC repository:
 
 ```dvc
 $ ls -a

static/docs/commands-reference/diff.md

@@ -51,11 +51,10 @@ by the Git SCM, for example when `dvc init` was used with the `--no-scm` option.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Examples: Previous version of the same branch
+## Examples
 
-For the setup of our examples we can use the steps in our
-[Get Started](/doc/get-started) guide up to the
-[Add Files](/doc/get-started/add-files) section.
+For these examples we can use the steps in our [Get Started](/doc/get-started)
+guide, up to the [Add Files](/doc/get-started/add-files) step.
 
 <details>
 
@@ -64,33 +63,26 @@ For the setup of our examples we can use the steps in our
 Start by cloning our sample repo if you don't already have it. Then move into
 the repo and checkout the
 [version](https://github.com/iterative/example-get-started/releases/tag/3-add-file)
-corresponding to the add-files section mentioned above
+corresponding to the _Add Files_ step:
 
 ```dvc
 $ git clone https://github.com/iterative/example-get-started
-Cloning into 'example-get-started'...
-
 $ cd example-get-started
 $ git checkout 3-add-file
-Note: checking out '3-add-file'...
-
-$ dvc pull
-Preparing to download data from 'https://remote.dvc.org/get-started'
-...
 ```
 
-Now let's create a virtual environment with
-[virtualenv](https://virtualenv.pypa.io/en/stable/) and install the
-requirements.
+Download the precomputed data using:
 
 ```dvc
-$ virtualenv -p python3 .env
-$ source .env/bin/activate
-$ pip install -r requirements.txt
+$ dvc pull
+Preparing to download data from 'https://remote.dvc.org/get-started'
+...
 ```
 
 </details>
 
+## Example: Previous version of the same branch
+
 The minimal `dvc diff` command only includes the A reference (`a_ref`) from
 which the difference is to be calculated. The B reference (`b_ref`) defaults to
 Git `HEAD` (the currently checked out version). To find the general differences
@@ -107,7 +99,7 @@ diff for 'data/data.xml'
 added file with size 37.9 MB
 ```
 
-## Examples: Specific targets across Git references
+## Example: Specific targets across Git references
 
 We can base this example in the [Experiment Metrics](/doc/get-started/metrics)
 and [Compare Experiments](/doc/get-started/compare-experiments) sections of our

static/docs/commands-reference/fetch.md

@@ -114,36 +114,19 @@ specified in DVC-files currently in the workspace are considered by `dvc fetch`
 
 ## Examples
 
-To explore `dvc fetch` let's consider a simple
-[pipeline](/doc/get-started/pipeline) with several stages and a few Git tags.
-Then we can see what happens with `fetch` as we shift from tag to tag with
-`git`.
+Let's employ a simple workspace with some stages and a few Git tags, such as our
+[get started example repo](https://github.com/iterative/example-get-started).
+Then we can see what happens with `dvc fetch` as we switch from tag to tag.
 
 <details>
 
 ### Click and expand to setup the project
 
-This step is optional, and you can run it only if you want to run this examples
-in your environment. First, you need to download the project:
+Start by cloning our sample repo if you don't already have it:
 
 ```dvc
 $ git clone https://github.com/iterative/example-get-started
-```
-
-Second, let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with
-[virtualenv](https://virtualenv.pypa.io/en/stable/) or a similar tool:
-
-```dvc
 $ cd example-get-started
-$ virtualenv -p python3 .env
-$ source .env/bin/activate
-```
-
-Now, we can install requirements for the project:
-
-```dvc
-$ pip install -r requirements.txt
 ```
 
 </details>
@@ -173,7 +156,7 @@ baseline     <- first simple version of the model
 bigram       <- use bigrams to improve the model
 ```
 
-## Examples: Default behavior
+## Example: Default behavior
 
 This project comes with a predefined HTTP
 [remote storage](/doc/commands-reference/remote). We can now just run
@@ -218,7 +201,7 @@ Checking out '{'scheme': 'local', 'path': '.../example-get-started/model.pkl'}'
 Checking out '{'scheme': 'local', 'path': '.../example-get-started/data/...
 ```
 
-## Examples: Specific stages
+## Example: Specific stages
 
 > Please delete the `.dvc/cache` directory first (with `rm -Rf .dvc/cache`) to
 > follow this example if you tried the previous one (**Default behavior**).
@@ -250,7 +233,7 @@ Cache entries for the necessary directories, as well as the actual
 `data/prepared/test.tsv` and `data/prepared/train.tsv` files were download,
 checksums shown above.
 
-## Examples: With dependencies
+## Example: With dependencies
 
 After following the previous example (**Specific stages**), only the files
 associated with the `prepare.dvc` stage file have been fetched. Several

static/docs/commands-reference/get.md

@@ -44,7 +44,7 @@ created in the current working directory, with its original file name.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Example
+## Examples
 
 > Note that `dvc get` can be used form anywhere in the file system, as long as
 > DVC is [installed](/doc/get-started/install).