Merge args linker path update (#131)

.github/workflows/update-commands.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Check
         run: |
           if [[ `git status packages/gatsby-theme-iterative/config/prismjs --porcelain` ]]; then
-           cml pr create packages/gatsby-theme-iterative/config/prismjs --title "Update tool commands" --message "update tool commands"
+           cml comment update --pr packages/gatsby-theme-iterative/config/prismjs --title "Update tool commands" --message "update tool commands"
           else 
             echo "No changes!"
           fi

CODEOWNERS

@@ -0,0 +1 @@
+* @iterative/websites

README.md

@@ -1,78 +1,8 @@
-# Gatsby Theme: Iterative
+# Gatsby Theme: Iterative development monorepo
 
-This Gatsby Theme houses the shared website code for all websites for
-[Iterative](https://iterative.ai). This package is currently purpose-built
-specifically for our websites and not very useful outside of them, but we intend
-to change that as we make improvements and iron out issues!
+This repo is dedicated to the development of `gatsby-theme-iterative`, a shared
+code bundle used between all the Gatsby websites hosted by
+[Iterative, inc](iterative.ai)!
 
-## Usage
-
-### Options
-
-- disable: boolean Default: Boolean(process.env.SKIP_DOCS)
-
-- getTemplate: function Default: () => defaultGetTemplate
-
-- defaultTemplate: string Default: require.resolve('./src/templates/doc.tsx')
-
-- remark: boolean Default: true
-
-- filesystem: boolean Default: true
-
-- glossaryDirectory: string Default: 'docs/user-guide/basic-concepts'
-
-- simpleLinkerTerms: { matches: string, url: string }[] These terms will be
-  passed to the simpleLinker remark plugin
-
-- cssBase: string Used as base files for global PostCSS variables and queries
-
-- customMediaConfig: object config passed to `postcss-custom-media`
-
-- customPropertiesConfig: object config passed to `postcss-custom-properties`
-
-- colorModConfig: object config passed to `postcss-color-mod`
-
-- postCssPlugins: Plugin[] If specified, this array will completely replace
-  plugins this theme passes to PostCSS. This is mostly an escape hatch for if
-  styles are broken with the default plugins. Check out
-  [the theme's `gatsby-config`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/gatsby-theme-iterative/gatsby-config.js)
-  to see the default plugins, as not having them in this option will very likely
-  break core functionality.
-
-### Examples
-
-See this example from
-[the example website's `gatsby-config.js`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/example/gatsby-config.js).
-
-```js
-const path = require('path')
-const {
-  name: themePackageName
-} = require('../gatsby-theme-iterative/package.json')
-
-module.exports = {
-  trailingSlash: 'never',
-  siteMetadata: {
-    title: 'Example website',
-    description: 'Example website description',
-    keywords: ['docs', 'test'],
-    siteUrl: 'http://localhost:8000'
-  },
-  plugins: [
-    {
-      resolve: themePackageName,
-      options: {
-        simpleLinkerTerms: require('./content/linked-terms')
-      }
-    },
-    {
-      resolve: 'gatsby-source-filesystem',
-      options: {
-        name: 'images',
-        path: path.join(__dirname, 'static', 'img')
-      }
-    },
-    '@sentry/gatsby'
-  ]
-}
-```
+For more details about the theme itself, check out its
+[README](packages/gatsby-theme-iterative/README.md)!

packages/example/content/docs/examples.md

@@ -85,3 +85,14 @@ To push the changes upstream, run:
     git push origin cv-class#dev#1 #this is a comment
 #This is a comment
 ```
+
+## Highlight --options-with-hypthen
+
+```cli
+$ cml runner launch \
+  --cloud=aws \
+  --cloud-region=us-west \
+  --cloud-type=m+t4 \
+  --cloud-permission-set=arn:aws:iam::1234567890:instance-profile/dvc-s3-access \
+  --labels=cml-gpu
+```

packages/example/content/docs/gto/command-reference/annotate.md

@@ -0,0 +1,86 @@
+# annotate
+
+Update artifact metadata annotations.
+
+## Synopsis
+
+```usage
+usage: gto annotate [-r <text>] [--type <text>] [--path <text>]
+                    [-e] [--label <text>] [-d <text>] [--commit]
+                    [--push] [-h]
+                    name
+
+arguments:
+  name             Artifact name
+```
+
+## Description
+
+The command adds the artifact annotation to `artifacts.yaml` file. Feel free to
+modify the file directly!
+
+For example,
+
+```cli
+$ gto annotate awesome-model \
+  --type model \
+  --path models/neural_network.h5 \
+  --label ml
+  --label cool
+  --description "This model is very cool"
+```
+
+will create
+
+```yaml
+awesome-model:
+  description: This model is very cool
+  labels:
+    - ml
+    - cool
+  path: models/neural_network.h5
+  type: model
+```
+
+This information can be later retrieved by running `gto describe` command.
+
+> Don't forget to commit `artifacts.yaml` with Git to associate it with the
+> latest artifact version and stage in any copy of the repo.
+
+By default GTO saves artifact as `virtual`. Use the `--must_exist` flag to tell
+GTO the artifact file is committed to Git.
+
+<details>
+
+### Virtual vs. Physical artifacts
+
+- Physical files/directories are committed to the repo. When you create a new
+  version or assign a stage to it, Git guarantees that it's immutable -- you can
+  return a year later and get the same artifact by providing a version.
+
+- Virtual artifacts could be an external path (e.g. `s3://mybucket/myfile`) or a
+  local path to a metafile representing an externally stored artifact file (as
+  [with DVC](https://dvc.org/doc/start/data-management)). In this case, GTO
+  can't pin versions to a physical state of the artifact and guarantee its
+  immutability later, e.g. if `s3://mybucket/myfile` changes the registry won't
+  know it, nor have a way to recover the original file.
+
+> In future versions, we will support additional enrichments: useful information
+> that other tools like [DVC](https://dvc.org/) and [MLEM](https://mlem.ai/) can
+> provide about the artifacts. This will allow treating DVC repo outputs as
+> usual artifacts instead of `virtual` ones.
+
+</details>
+
+## Options
+
+- `-r <text>`, `--repo <text>` - Local or remote repository [default: .]
+- `--type <text>` - Artifact type
+- `--path <text>` - Artifact path
+- `-e`, `--must-exist` - Verify artifact is committed to Git
+- `--label <text>` - Labels to add to artifact
+- `-d <text>`, `--description <text>` - Artifact description
+- `--commit` - Automatically commit changes due to this command (experimental)
+- `--push` - Push created commit automatically (experimental) - will set
+  commit=True
+- `-h`, `--help` - Show this message and exit.

packages/example/content/docs/gto/command-reference/assign.md

@@ -0,0 +1,61 @@
+# assign
+
+Assign stage to specific artifact version.
+
+## Synopsis
+
+```usage
+usage: gto assign [-r <text>] [--version <text>]
+                  [--stage <text>] [-m <text>]
+                  [--simple <text>] [--force] [--push] [--sr]
+                  [-h]
+                  name [ref]
+
+arguments:
+  name             Artifact name
+  [ref]            Git reference to use
+```
+
+## Description
+
+To assign an actionable stage for a specific artifact version use the same
+`gto assign` command. Stages can mark the artifact readiness for a specific
+consumer. You can plug in a real downsteam system via CI/CD or web hooks, e.g.
+to redeploy an ML model.
+
+```cli
+$ gto assign awesome-model --version v0.0.1 --stage prod
+Created git tag 'awesome-model#prod#1' that assigns stage to 'v0.0.1'
+```
+
+GTO creates a special Git tag in
+[the standard format](/doc/gto/user-guide/git-tags).
+
+## Options
+
+- `-r <text>`, `--repo <text>` - Local or remote repository [default: .]
+- `--version <text>` - If you provide REF, this will be used to name new version
+- `--stage <text>` - Stage to assign
+- `-m <text>`, `--message <text>` - Message to annotate the Git tag with
+- `--simple <text>` - Use simple notation, e.g. `rf#prod` instead of `rf#prod-5`
+  [supported values: auto, true, false] [default: auto]
+- `--force` - Create the Git tag even if it already exists and is in effect
+- `--push` - Push created tag automatically (experimental)
+- `--sr`, `--skip-registration` - Don't register a version at specified commit
+- `-h`, `--help` - Show this message and exit.
+
+## Examples
+
+Assign artifact "nn" to "prod" at specific Git ref instead of supplying artifact
+version (note that this will also register a version if it doesn't exist):
+
+```cli
+$ gto assign nn abcd123 --stage prod
+```
+
+Assign stage at specific Git ref and name the version explicitly (this assumes
+that version was not registered yet):
+
+```cli
+$ gto assign nn abcd123 --version v1.0.0 --stage prod
+```

packages/example/content/docs/gto/command-reference/check-ref.md

@@ -0,0 +1,36 @@
+# check-ref
+
+Find out the artifact version registered/assigned with ref.
+
+## Synopsis
+
+```usage
+usage: gto check-ref [-r <text>] [--json] [--name] [--version]
+                     [--event] [--stage] [-h]
+                     ref
+
+arguments:
+  ref              Git reference to analyze
+```
+
+## Description
+
+You can use `gto check-ref` to interpret a Git tag:
+
+```cli
+$ gto check-ref -r build/example-gto churn#prod#3
+✅  Stage "prod" was assigned to version "v3.0.0" of artifact "churn"
+```
+
+For machine-consumable format, use `--json` flag or output specific pieces of
+information with `--name`, `--version`, `--stage` or `--event`.
+
+## Options
+
+- `-r <text>`, `--repo <text>` - Local or remote repository [default: .]
+- `--json` - Print output in json format
+- `--name` - Show artifact name
+- `--version` - Output artifact version
+- `--event` - Show event
+- `--stage` - Show artifact stage
+- `-h`, `--help` - Show this message and exit.