Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

readme: more VS Code Extension info. #7916

Merged
merged 11 commits into from Jun 20, 2022
Merged

readme: more VS Code Extension info. #7916

Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a7bdc1e
readme: intro updates (VSCE)
jorgeorpinel Jun 17, 2022
0f28652
readme: blocks to link to DVC GS
jorgeorpinel Jun 17, 2022
b84366f
readme: Link current Quick start to Cmd Ref
jorgeorpinel Jun 17, 2022
04fd858
readme: add VS Code to Installation list + formatting
jorgeorpinel Jun 17, 2022
b06bbef
Update README.rst
jorgeorpinel Jun 18, 2022
d3c0f08
readme: add VS Code Extension sction and gif
jorgeorpinel Jun 18, 2022
ac96fc5
readme: fix link
jorgeorpinel Jun 18, 2022
5482de3
readme: roll back non-vscode changes
jorgeorpinel Jun 19, 2022
8fdaec5
readme: single QS, VSC gif in Install
jorgeorpinel Jun 19, 2022
d003755
Merge branch 'main' into readme/vsce
jorgeorpinel Jun 20, 2022
5a1f9b0
readme: make VS Code installation into a separate section.
jorgeorpinel Jun 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
93 changes: 54 additions & 39 deletions README.rst
View file
Open in desktop
Expand Up @@ -2,21 +2,20 @@

`Website <https://dvc.org>`_
• `Docs <https://dvc.org/doc>`_
• `VS Code Extension <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_
• `Blog <http://blog.dataversioncontrol.com>`_
• `Twitter <https://twitter.com/DVCorg>`_
• `Chat (Community & Support) <https://dvc.org/chat>`_
• `Tutorial <https://dvc.org/doc/get-started>`_
• `Mailing List <https://sweedom.us10.list-manage.com/subscribe/post?u=a08bf93caae4063c4e6a351f6&id=24c0ecc49a>`_
• `VS Code Extension <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_

|CI| |Maintainability| |Coverage| |VS Code| |DOI|

|PyPI| |Packages| |Brew| |Conda| |Choco| |Snap|

|

**Data Version Control** or **DVC** helps you develop reproducible machine
learning projects:
**Data Version Control** or **DVC** is a command line tool and `VS Code Extension <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_ to help you develop reproducible machine learning projects:

#. **Version** your data and models. Store them in your cloud storage but keep
their version info in your Git repo.
Expand All @@ -26,9 +25,7 @@ learning projects:

#. **Track** experiments in your local Git repo (no servers needed).

#. **Compare** any data, code, parameters, metrics, or plots from the command
line or in `VS Code
<https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_.
#. **Compare** any data, code, parameters, model, or performance plots

#. **Share** experiments and automatically reproduce anyone's experiment.

Expand All @@ -38,8 +35,9 @@ learning projects:
How DVC works
=============

We encourage you to read our `Get Started <https://dvc.org/doc/get-started>`_ guide to better understand what DVC
is and how it can fit your scenarios.
We encourage you to read our `Get Started
<https://dvc.org/doc/get-started>`_ guides to better understand what DVC
does and how it can fit your scenarios.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not directly related but we should probably move this to AFTER the Quick start sections?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • BTW it's missing info about Experiment Management (only covers Data Mgmt and Pipelines rn)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes on both counts! It's on my personal to-do list along with a host of other readme improvements.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#7917

jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

The easiest (but not perfect!) *analogy* to describe it: DVC is Git (or Git-LFS to be precise) & Makefiles
made right and tailored specifically for ML and Data Science scenarios.
Expand All @@ -56,21 +54,32 @@ Google Cloud, etc) or any on-premise network storage (via SSH, for example).

The DVC pipelines (computational graph) feature connects code and data together. It is possible to explicitly
specify all steps required to produce a model: input dependencies including data, commands to run,
and output information to be saved. See the quick start section below or
and output information to be saved. See the quick start sections below or
the `Get Started <https://dvc.org/doc/get-started>`_ tutorial to learn more.

Quick start
===========
Quick start (Visual Studio Code)
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
================================

#. `Install DVC <https://dvc.org/doc/install>`_ on your system.
#. Install the `DVC extension <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_ for VS Code.
#. Follow the **Get Started** page that pops up!

|VS Code Extension Overview|

Quick start (command line)
==========================

Please read `Get Started <https://dvc.org/doc/get-started>`_ guide for a full version. Common workflow commands include:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why get rid of this? I know it's above, but considering we will want to swap places, it would be good to link to get started early.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was removed because there's 2 Quick starts now, this one is specific to command line so I linked to the Command Reference docs instead.

Please read our `Command Reference <https://dvc.org/doc/command-reference>`_ for a complete list.

A common CLI workflow includes:
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

+-----------------------------------+----------------------------------------------------------------------------+
| Step | Command |
| Task | Terminal |
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
+===================================+============================================================================+
| Track data | | ``$ git add train.py`` |
| | | ``$ dvc add images.zip`` |
+-----------------------------------+----------------------------------------------------------------------------+
| Connect code and data by commands | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` |
| Connect code and data | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` |
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
| | | ``$ dvc run -n train -d images/ -d train.py -o model.p python train.py`` |
+-----------------------------------+----------------------------------------------------------------------------+
| Make changes and reproduce | | ``$ vi train.py`` |
Expand All @@ -87,14 +96,21 @@ Please read `Get Started <https://dvc.org/doc/get-started>`_ guide for a full ve
Installation
============

There are four options to install DVC: ``pip``, Homebrew, Conda (Anaconda) or an OS-specific package.
There are several ways to install DVC: in VS Code; using ``snap``, ``choco``, ``brew``, ``conda``, ``pip``; or with an OS-specific package.
Full instructions are `available here <https://dvc.org/doc/get-started/install>`_.

To use with VS Code, install DVC and then install the `DVC Extension
<https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_.
Visual Studio Code Extension
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
----------------------------

|VS Code|

To get DVC features embedded right into your VS Code IDE, install the `DVC Extension <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>`_ from the Marketplace.

Snap (Snapcraft/Linux)
----------------------
Note: You'll also have to install core DVC in your system in one of the
other ways listed below. The Extension will guide you if needed.

Snapcraft (Linux)
-----------------

|Snap|

Expand All @@ -103,29 +119,28 @@ Snap (Snapcraft/Linux)
snap install dvc --classic

This corresponds to the latest tagged release.
Add ``--beta`` for the latest tagged release candidate,
or ``--edge`` for the latest ``main`` version.
Add ``--beta`` for the latest tagged release candidate, or ``--edge`` for the latest ``main`` version.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

Choco (Chocolatey/Windows)
--------------------------
Chocolatey (Windows)
--------------------
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

|Choco|

.. code-block:: bash

choco install dvc

Brew (Homebrew/Mac OS)
----------------------
Brew (mac OS)
-------------
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

|Brew|

.. code-block:: bash

brew install dvc

Conda (Anaconda)
----------------
Anaconda (Any platform)
-----------------------
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

|Conda|

Expand All @@ -134,36 +149,33 @@ Conda (Anaconda)
conda install -c conda-forge mamba # installs much faster than conda
mamba install -c conda-forge dvc

Depending on the remote storage type you plan to use to keep and share your data, you might need to
install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`.
Depending on the remote storage type you plan to use to keep and share your data, you might need to install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

pip (PyPI)
----------
PyPI (Python)
-------------
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

|PyPI|

.. code-block:: bash

pip install dvc

Depending on the remote storage type you plan to use to keep and share your data, you might need to specify
one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all.
The command should look like this: ``pip install dvc[s3]`` (in this case AWS S3 dependencies such as ``boto3``
will be installed automatically).
Depending on the remote storage type you plan to use to keep and share your data, you might need to specify one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all.
The command should look like this: ``pip install 'dvc[s3]'`` (in this case AWS S3 dependencies such as ``boto3`` will be installed automatically).
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

To install the development version, run:

.. code-block:: bash

pip install git+git://github.com/iterative/dvc

Package
-------
Package (Platform-specific)
---------------------------
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

|Packages|

Self-contained packages for Linux, Windows, and Mac are available. The latest version of the packages
can be found on the GitHub `releases page <https://github.com/iterative/dvc/releases>`_.
Self-contained packages for Linux, Windows, and Mac are available.
The latest version of the packages can be found on the GitHub `releases page <https://github.com/iterative/dvc/releases>`_.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

Ubuntu / Debian (deb)
^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -257,6 +269,9 @@ Barrak, A., Eghan, E.E. and Adams, B. `On the Co-evolution of ML Pipelines and S
:target: https://dvc.org
:alt: DVC logo

.. |VS Code Extension Overview| image:: https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/docs/overview.gif
:alt: DVC Extension for VS Code

.. |CI| image:: https://github.com/iterative/dvc/workflows/Tests/badge.svg?branch=main
:target: https://github.com/iterative/dvc/actions
:alt: GHA Tests
Expand Down