From 10c1b52923f3a7aa630edc235b096341c293bcfc Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 8 Apr 2020 00:22:30 -0500 Subject: [PATCH 1/3] scripts: small update for link-check --- README.md | 2 +- package.json | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f3618b42de..b1bcb3fd6f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ code. Make sure you have the latest LTS version of [Node.js](https://nodejs.org) and [Yarn](https://yarnpkg.com) installed. -Run `yarn command`. +Run `yarn`. ## Commands diff --git a/package.json b/package.json index 316479f009..2b33043311 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,6 @@ "main": "index.js", "scripts": { "develop": "gatsby develop", - "debug": "node --inspect-brk server.js", "build": "gatsby build", "heroku-postbuild": "./scripts/deploy-with-s3.js", "test": "jest", @@ -15,8 +14,8 @@ "format-all": "prettier --write './**/*.{js,jsx,md,tsx,ts,json}'", "lint-ts": "tsc --noEmit --skipLibCheck && eslint --ext .json,.js,.ts,.tsx src scripts", "lint-css": "stylelint \"src/**/*.css\"", - "link-check": "scripts/link-check-git-all.sh", - "link-check-diff": "scripts/link-check-git-diff.sh" + "link-check": "./scripts/link-check-git-all.sh", + "link-check-diff": "./scripts/link-check-git-diff.sh" }, "repository": { "type": "git", From 37cb78f0883f537bd1cb6aad469d411c40e6c247 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 8 Apr 2020 01:10:34 -0500 Subject: [PATCH 2/3] scripts: fix link-check bad pages path per https://github.com/iterative/dvc.org/issues/1123#issuecomment-610766116 --- scripts/link-check-git-all.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/link-check-git-all.sh b/scripts/link-check-git-all.sh index 84da16a85b..27c78fea74 100755 --- a/scripts/link-check-git-all.sh +++ b/scripts/link-check-git-all.sh @@ -2,5 +2,5 @@ repo="$(dirname "$(realpath "$(dirname "$0")")")" -(find "$repo"/pages/ "$repo"/content/docs/ "$repo"/src/ "$repo"/.github/ -name '*.md' -o -name '*.js' && ls "$repo"/*.md "$repo"/*.js) \ +(find "$repo"/.github/ "$repo"/content/docs/ "$repo"/src/ -name '*.md' -o -name '*.js' && ls "$repo"/*.md "$repo"/*.js) \ | xargs -n1 -P8 $(dirname "$0")/link-check.sh From 6f80806996bd9a75cd66486ef0eae0c46620673d Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 8 Apr 2020 16:15:38 -0500 Subject: [PATCH 3/3] term: review usage of "section" --- content/docs/changelog/0.18.md | 4 ++-- content/docs/changelog/0.35.md | 6 +++--- content/docs/command-reference/checkout.md | 6 +++--- content/docs/command-reference/commit.md | 6 +++--- content/docs/command-reference/config.md | 8 ++++---- content/docs/command-reference/fetch.md | 6 +++--- content/docs/command-reference/import-url.md | 10 +++++----- content/docs/command-reference/import.md | 8 ++++---- content/docs/command-reference/index.md | 6 +++--- content/docs/command-reference/metrics/remove.md | 2 +- content/docs/command-reference/metrics/show.md | 4 ++-- content/docs/command-reference/pull.md | 2 +- content/docs/command-reference/remote/modify.md | 6 +++--- content/docs/tutorials/deep/define-ml-pipeline.md | 2 +- content/docs/tutorials/index.md | 4 ++-- content/docs/tutorials/versioning.md | 2 +- content/docs/use-cases/data-registries.md | 3 +-- content/docs/use-cases/sharing-data-and-model-files.md | 4 ++-- content/docs/user-guide/contributing/core.md | 4 ++-- content/docs/user-guide/contributing/docs.md | 6 +++--- content/docs/user-guide/index.md | 6 +++--- content/docs/user-guide/troubleshooting.md | 3 +-- 22 files changed, 53 insertions(+), 55 deletions(-) diff --git a/content/docs/changelog/0.18.md b/content/docs/changelog/0.18.md index 24fa0be71b..91438237a6 100644 --- a/content/docs/changelog/0.18.md +++ b/content/docs/changelog/0.18.md @@ -21,8 +21,8 @@ really excited to share the progress with you: - Commands startup latency reduced 3x -- πŸ“™ **Documentation got better** - a whole ne - [Get Started](/doc/tutorials/get-started) section, new +- πŸ“™ **Documentation got better** - a whole new + [Get Started](/doc/tutorials/get-started) tutorial, new [Use Cases](/doc/use-cases), [User Guide](/doc/user-guide), and lot of other great stuff you can find here. diff --git a/content/docs/changelog/0.35.md b/content/docs/changelog/0.35.md index 60889aeb16..67bf7fa6ec 100644 --- a/content/docs/changelog/0.35.md +++ b/content/docs/changelog/0.35.md @@ -13,12 +13,12 @@ improvements) we have done in the last few months: all DVC commands that also have `-a` or `--all-branches` (use all Git branches). -- πŸ“– The [Get Started](/doc/tutorials/get-started/agenda) section has been +- πŸ“– The [Get Started](/doc/tutorials/get-started/agenda) tutorial has been simplified (e.g. to use tags instead of branches) and extended. We have also prepared a [DVC project on GitHub](https://github.com/iterative/example-get-started) that - reflects the sequence of chapters in the β€œget started” section. You can now - download the whole project and reproduce all the models. + reflects the sequence of chapters in the Get Started. You can now download the + whole project and reproduce all the models. - **`dvc diff`** **command introduced**. Summary statistics for the directory/file tracked by DVC. How many files were diff --git a/content/docs/command-reference/checkout.md b/content/docs/command-reference/checkout.md index 31859673ff..c61d8520a6 100644 --- a/content/docs/command-reference/checkout.md +++ b/content/docs/command-reference/checkout.md @@ -101,9 +101,9 @@ be pulled from remote storage using `dvc pull`. ## Examples Let's employ a simple workspace with some data, code, ML models, -pipeline stages, such as the DVC project created in our -[Get Started](/doc/tutorials/get-started) section. Then we can see what happens -with `git checkout` and `dvc checkout` as we switch from tag to tag. +pipeline stages, such as the DVC project created for the +[Get Started](/doc/tutorials/get-started). Then we can see what happens with +`git checkout` and `dvc checkout` as we switch from tag to tag.
diff --git a/content/docs/command-reference/commit.md b/content/docs/command-reference/commit.md index ff4366ec74..6911f1d9cd 100644 --- a/content/docs/command-reference/commit.md +++ b/content/docs/command-reference/commit.md @@ -96,9 +96,9 @@ reproducibility in those cases. ## Examples Let's employ a simple workspace with some data, code, ML models, -pipeline stages, such as the DVC project created in our -[Get Started](/doc/tutorials/get-started) section. Then we can see what happens -with `git commit` and `dvc commit` in different situations. +pipeline stages, such as the DVC project created for the +[Get Started](/doc/tutorials/get-started). Then we can see what happens with +`git commit` and `dvc commit` in different situations.
diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md index fa526efe14..162c8ed4ef 100644 --- a/content/docs/command-reference/config.md +++ b/content/docs/command-reference/config.md @@ -16,8 +16,8 @@ positional arguments: ## Description You can query/set/replace/unset DVC configuration options with this command. It -takes a config option `name` (a section and a key, separated by a dot) and its -`value` (any valid alpha-numeric string generally). +takes a config option `name` (a config section and a key, separated by a dot) +and its `value` (any valid alpha-numeric string generally). This command reads and updates the DVC configuration files. By default (if none of `--local`, `--global`, or `--system` is provided) a project's config @@ -92,8 +92,8 @@ This is the main section with the general config options: ### remote -These are sections in the config file that describe particular remotes. These -sections contain a `url` value, and can also specify `user`, `port`, `keyfile`, +These are sections in the config file that describe particular remotes. They +contain a `url` value, and can also specify `user`, `port`, `keyfile`, `timeout`, `ask_password`, and other cloud-specific key/value pairs for each remote. See `dvc remote` for more information. diff --git a/content/docs/command-reference/fetch.md b/content/docs/command-reference/fetch.md index 47e2b7fc49..f8d56bb070 100644 --- a/content/docs/command-reference/fetch.md +++ b/content/docs/command-reference/fetch.md @@ -115,9 +115,9 @@ considered by `dvc fetch` (unless the `-a` or `-T` options are used). ## Examples Let's employ a simple workspace with some data, code, ML models, -pipeline stages, such as the DVC project created in our -[Get Started](/doc/tutorials/get-started) section. Then we can see what happens -with `dvc fetch` as we switch from tag to tag. +pipeline stages, such as the DVC project created for the +[Get Started](/doc/tutorials/get-started). Then we can see what happens with +`dvc fetch` as we switch from tag to tag.
diff --git a/content/docs/command-reference/import-url.md b/content/docs/command-reference/import-url.md index 564bb78458..01c5cadfb9 100644 --- a/content/docs/command-reference/import-url.md +++ b/content/docs/command-reference/import-url.md @@ -40,9 +40,9 @@ desired for the downloaded data. If an existing directory is specified, the DVC supports [DVC-files](/doc/user-guide/dvc-file-format) that refer to data in external locations, see [External Dependencies](/doc/user-guide/external-dependencies). In such a -DVC-file, the `deps` section stores the remote URL, and the `outs` section -contains the corresponding local path in the workspace. It records metadata from -the external file or directory, allowing DVC to efficiently check it later and +DVC-file, the `deps` field stores the remote URL, and the `outs` field contains +the corresponding local path in the workspace. It records metadata from the +external file or directory, allowing DVC to efficiently check it later and determine whether the local copy is out of date. DVC supports several types of (local or) remote locations (protocols): @@ -123,7 +123,7 @@ up to date from the external data source. ## Examples To illustrate these examples we will be using the project explained -in the [Get Started](/doc/tutorials/get-started) section. +in the [Get Started](/doc/tutorials/get-started).
@@ -150,7 +150,7 @@ You should now have a blank workspace, just before the ## Example: Tracking a remote file An advanced alternate to [Add Files](/doc/tutorials/get-started/add-files) -chapter of the _Get Started_ section is to use `dvc import-url`: +chapter of the _Get Started_ is to use `dvc import-url`: ```dvc $ dvc import-url https://data.dvc.org/get-started/data.xml \ diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md index 04a16261b0..fe70d87b9e 100644 --- a/content/docs/command-reference/import.md +++ b/content/docs/command-reference/import.md @@ -59,10 +59,10 @@ extending the name of the imported data e.g. `data.txt.dvc` – similar to havin used `dvc run` to generate the output. DVC-files support references to data in an external DVC repository (hosted on a -Git server). In such a DVC-file, the `deps` section specifies the `repo`-`url` -and data `path` fields, and the `outs` section contains the corresponding local -workspace `path` field. This is enough data about the imported data, to enable -DVC efficiently determining whether the local copy is out of date. +Git server). In such a DVC-file, the `deps` field specifies the `repo`-`url` and +data `path` sufields, and the `outs` field contains the corresponding local +workspace `path` subfield. This is enough data about the imported data, to +enable DVC efficiently determining whether the local copy is out of date. To actually [track the data](https://dvc.org/doc/tutorials/get-started/add-files), `git add` diff --git a/content/docs/command-reference/index.md b/content/docs/command-reference/index.md index be236fb0d3..865d0e3885 100644 --- a/content/docs/command-reference/index.md +++ b/content/docs/command-reference/index.md @@ -16,7 +16,7 @@ DVC is a command line tool. The typical DVC workflow goes as follows: - Use `dvc repro` to automatically reproduce your full pipeline, iteratively as input data or source code change. -The command references under this section provide a precise specification, -complete description, and isolated usage examples for the `dvc` CLI tool. These -are our most technical documentation pages, similar to +These command references provide a precise specification, complete description, +and isolated usage examples for the `dvc` CLI tool. These are our most technical +documentation pages, similar to [man-pages](https://www.kernel.org/doc/man-pages/) in Linux. diff --git a/content/docs/command-reference/metrics/remove.md b/content/docs/command-reference/metrics/remove.md index 1e22fcb9cb..17aa864cd6 100644 --- a/content/docs/command-reference/metrics/remove.md +++ b/content/docs/command-reference/metrics/remove.md @@ -81,7 +81,7 @@ Now, let's reset the `metric` field with the `dvc metrics remove` command: $ dvc metrics remove metrics.json ``` -Let's check the outputs section (`outs`) of same +Let's check the outputs field (`outs`) of same [DVC-file](/doc/user-guide/dvc-file-format) again: ```yaml diff --git a/content/docs/command-reference/metrics/show.md b/content/docs/command-reference/metrics/show.md index 89b4d28b7e..e0c59595e6 100644 --- a/content/docs/command-reference/metrics/show.md +++ b/content/docs/command-reference/metrics/show.md @@ -106,5 +106,5 @@ Examples in [add](/doc/command-reference/metrics/add), for the `dvc metrics show`. The [Compare Experiments](/doc/tutorials/get-started/compare-experiments) -chapter of our _Get Started_ section covers the `-a` option to collect and print -a metric file value across all Git branches. +chapter of our _Get Started_ covers the `-a` option to collect and print a +metric file value across all Git branches. diff --git a/content/docs/command-reference/pull.md b/content/docs/command-reference/pull.md index c3fc32da4a..195056d483 100644 --- a/content/docs/command-reference/pull.md +++ b/content/docs/command-reference/pull.md @@ -137,7 +137,7 @@ $ dvc pull data.zip.dvc In this case we left off the `--remote` option, so it will have pulled from the default remote. The only files considered in this case are what is listed in the -`out` section of the DVC-file `targets`. +`out` field of the DVC-file `targets`. ## Example: With dependencies diff --git a/content/docs/command-reference/remote/modify.md b/content/docs/command-reference/remote/modify.md index 159eb9f774..68742bc18d 100644 --- a/content/docs/command-reference/remote/modify.md +++ b/content/docs/command-reference/remote/modify.md @@ -27,9 +27,9 @@ positional arguments: ## Description Remote `name` and `option` name are required. Config option names are specific -to the remote type. See `dvc remote add` and the -[available settings](#available-settings-per-storage-type) section below for a -list of remote storage types. +to the remote type. See `dvc remote add` and +[Available settings](#available-settings-per-storage-type) below for a list of +remote storage types. This command modifies a `remote` section in the project's [config file](/doc/command-reference/config). Alternatively, `dvc config` or diff --git a/content/docs/tutorials/deep/define-ml-pipeline.md b/content/docs/tutorials/deep/define-ml-pipeline.md index 2de0fd8fba..c729486732 100644 --- a/content/docs/tutorials/deep/define-ml-pipeline.md +++ b/content/docs/tutorials/deep/define-ml-pipeline.md @@ -221,7 +221,7 @@ outs: path: data/Posts.xml ``` -Sections of the file above include: +Parent fields in the file above include: - `cmd`: The command to run - `deps`: Dependencies with MD5 hashes diff --git a/content/docs/tutorials/index.md b/content/docs/tutorials/index.md index 8eed7fe924..f0b649e52d 100644 --- a/content/docs/tutorials/index.md +++ b/content/docs/tutorials/index.md @@ -1,7 +1,7 @@ # Tutorials -The material in this section is designed to help new and intermediate users -learn about DVC interactively. +Our tutorials designed to help new and intermediate users learn about DVC +interactively. - [Get Started](/doc/tutorials/get-started) is a step-by-step introduction into basic DVC features. It doesn't go into much detail, but it provides links and diff --git a/content/docs/tutorials/versioning.md b/content/docs/tutorials/versioning.md index 370fc95165..a770a7a4e7 100644 --- a/content/docs/tutorials/versioning.md +++ b/content/docs/tutorials/versioning.md @@ -301,7 +301,7 @@ above (with cats and dogs images) is a good example. On the other hand, there are files that are the result of running some code. In our example, `train.py` produces binary files (e.g. -`bottlneck_features_train.npy`), the model file `model.h5`, and the +`bottleneck_features_train.npy`), the model file `model.h5`, and the [metrics](/doc/command-reference/metrics) file `metrics.csv`. When you have a script that takes some data as an input and produces other data diff --git a/content/docs/use-cases/data-registries.md b/content/docs/use-cases/data-registries.md index 558cdcbcbd..8ef1f1662d 100644 --- a/content/docs/use-cases/data-registries.md +++ b/content/docs/use-cases/data-registries.md @@ -49,8 +49,7 @@ Data registries can be created like any other DVC repository with directories, to group the data into separate uses, such as `images/`, `natural-language/`, etc. For example, our [dataset-registry](https://github.com/iterative/dataset-registry) uses a -directory for each section in our website documentation, like `get-started/`, -`use-cases/`, etc. +directory for each part in our docs, like `get-started/`, `use-cases/`, etc. Adding datasets to a registry can be as simple as placing the data file or directory in question inside the workspace, and telling DVC to diff --git a/content/docs/use-cases/sharing-data-and-model-files.md b/content/docs/use-cases/sharing-data-and-model-files.md index 77c583e562..2332f409cb 100644 --- a/content/docs/use-cases/sharing-data-and-model-files.md +++ b/content/docs/use-cases/sharing-data-and-model-files.md @@ -38,8 +38,8 @@ Setting 'myremote' as a default remote. > The `-d` (`--default`) option sets `myremote` as the default remote storage > for this project. -This will add `myremote` to your `.dvc/config`. The `config` file now have a -section like this: +This will add `myremote` to your `.dvc/config`. The `config` file now has a +remote section for it: ```dvc ['remote "myremote"'] diff --git a/content/docs/user-guide/contributing/core.md b/content/docs/user-guide/contributing/core.md index 77c68e375e..e45529bd21 100644 --- a/content/docs/user-guide/contributing/core.md +++ b/content/docs/user-guide/contributing/core.md @@ -164,8 +164,8 @@ created a template for you: $ cp tests/remotes_env.sample tests/remotes_env ``` -Then uncomment lines you need and fill in needed values, the details are -explained in remote specific subsections. To activate these environment +Then uncomment the lines you need and fill in the values, the details are +explained in remote-specific subsections. To activate these environment variables, use: ```dvc diff --git a/content/docs/user-guide/contributing/docs.md b/content/docs/user-guide/contributing/docs.md index 7728c00edf..64f52e30e6 100644 --- a/content/docs/user-guide/contributing/docs.md +++ b/content/docs/user-guide/contributing/docs.md @@ -15,9 +15,9 @@ To contribute documentation, these are the relevant locations: - [Images](https://github.com/iterative/dvc.org/tree/master/static/img) (`img/`): Add new images (png, svg, etc.) here. Use them in Markdown files like this: `![](/img/.gif)`. -- [Sections](https://github.com/iterative/dvc.org/tree/master/content/docs/sidebar.json) - (`docs/sidebar.json`): Edit it to register a new section for the navigation - menu. +- [Navigation](https://github.com/iterative/dvc.org/tree/master/content/docs/sidebar.json) + (`docs/sidebar.json`): Edit it to add or change entries in the navigation + sidebar. Merging the appropriate changes to these files into the master branch is enough to update the docs and redeploy the website. diff --git a/content/docs/user-guide/index.md b/content/docs/user-guide/index.md index 2b5a8a8a47..e51926f40b 100644 --- a/content/docs/user-guide/index.md +++ b/content/docs/user-guide/index.md @@ -1,12 +1,12 @@ # User Guide -This section describes the main DVC concepts and features comprehensively, +Our guides describe the main DVC concepts and features comprehensively, explaining when and how to use them, as well as connections between them. These guides don't focus on specific scenarios, but have a general scope – like a user manual. Their topics range from more technical foundations, impacting more parts of DVC, to more advanced and specific things you can do. We also include a few -guides related to contributing to this -[open-source project](https://github.com/iterative/dvc). +guides related to contributing to +[this open-source project](https://github.com/iterative/dvc). Please choose from the navigation sidebar to the left, or click the `Next` button below β†˜ diff --git a/content/docs/user-guide/troubleshooting.md b/content/docs/user-guide/troubleshooting.md index f2f306e3e8..7eafdac592 100644 --- a/content/docs/user-guide/troubleshooting.md +++ b/content/docs/user-guide/troubleshooting.md @@ -1,7 +1,6 @@ # Troubleshooting -In this section we provide help for some of the problems that DVC user might -stumble upon. +Here we provide help for some of the problems that DVC user might stumble upon.