feature: update docs for v1.3.0

tools/install.sh

@@ -7,9 +7,7 @@ OS="$(uname -s | tr A-Z a-z)"
 ARCH=$(test "$(uname -m)" = 'x86_64' && echo 'amd64' || echo 'arm64')
 
 cd ${TEMPDIR}
-ORAS_COMMAND="${TEMPDIR}/oras"
 OUTPUT_FILE="${TEMPDIR}/oras.tgz"
 curl -s -o ${OUTPUT_FILE} -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_${OS}_${ARCH}.tar.gz" >&2
 tar -zxf ${OUTPUT_FILE} oras >&2
 rm -f ${OUTPUT_FILE}
-echo "${ORAS_COMMAND}"

tools/list_commands.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+COMMAND="${1?First argument is command}"
+
+STATE='Usage'
+oras help ${COMMAND} | grep -v '^  completion'| while read LINE
+do
+    [[ "${LINE}" == "" ]] && continue
+
+    case "${STATE}" in
+    Usage)
+        if [[ "${LINE}" == Available* ]]
+        then
+            STATE='Commands'
+            continue
+        fi
+        ;;
+    Commands)
+        if [[ "${LINE}" == Flags* ]]
+        then
+            STATE='Flags'
+            continue
+        fi
+        COMMAND=$(echo "${LINE}" | sed -e 's/^[[:space:]]*//' | sed -e 's/[[:space:]].*//')
+        echo ${COMMAND}
+        ;;
+    Flags)
+        ;;
+    esac
+done

tools/parse.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 
-TEMPDIR="${1?First argument is temporary directory}"
-COMMAND="${2?Second argument is command to run}"
-WEIGHT="${3?Third argument is weight}"
-ORAS="${TEMPDIR}/oras"
+COMMAND="${1?First argument is command to run}"
+WEIGHT="${2?Second argument is weight}"
+
+TEMPDIR=$(mktemp -d)
+trap 'rm -rf "$TEMPDIR"' EXIT
 
 echo '---'
 echo "title: oras ${COMMAND}"
@@ -20,7 +21,7 @@ echo
 TEMPFILE="${TEMPDIR}/help"
 EXAMPLES_FILE="${TEMPDIR}/examples"
 trap 'rm -f "$TEMPFILE" "$EXAMPLES_FILE"' EXIT
-${ORAS} help ${COMMAND} >${TEMPFILE}
+oras help ${COMMAND} >${TEMPFILE}
 
 IFS=''
 STATE=Introduction

tools/refresh-commands.sh

@@ -21,76 +21,14 @@ map_version() {
     grep "^$1" versions-latest || echo "$1.0"
 }
 
-list_commands() {
-    STATE='Usage'
-    IFS=''
-    ${ORAS_COMMAND} help ${1} | grep -v '^  completion'| while read LINE
-    do
-        [[ "${LINE}" == "" ]] && continue
-
-        case "${STATE}" in
-        Usage)
-            if [[ "${LINE}" == Available* ]]
-            then
-                STATE='Commands'
-                continue
-            fi
-            ;;
-        Commands)
-            if [[ "${LINE}" == Flags* ]]
-            then
-                STATE='Flags'
-                continue
-            fi
-            COMMAND=$(echo "${LINE}" | sed -e 's/^[[:space:]]*//' | sed -e 's/[[:space:]].*//')
-            echo ${COMMAND}
-            ;;
-        Flags)
-            ;;
-        esac
-    done
-}
-
-DIFFS=false
 VERSIONS=$(tr '[]",' ' ' <versions.json)
 for VERSION
 in ${VERSIONS}
 do
     LATEST_VERSION=$(map_version $VERSION)
-    ORAS_COMMAND=$(./tools/install.sh ${LATEST_VERSION} ${TEMPDIR})
-    WEIGHT=10
+    ./tools/install.sh ${LATEST_VERSION} ${TEMPDIR}
+    export PATH=${TEMPDIR}:${PATH}
     VERSIONED_DOCS=versioned_docs/version-${VERSION}/commands
-    ${ORAS_COMMAND} help | ./tools/parse_main.sh >"${VERSIONED_DOCS}/use_oras_cli.mdx"
-    list_commands >"${TEMPDIR}/commands"
-    while read COMMAND
-    do
-        list_commands "${COMMAND}" >"${TEMPDIR}/subcommands"
-        if [ ! -s "${TEMPDIR}/subcommands" ]
-        then
-            FILE="${VERSIONED_DOCS}/oras_${COMMAND}.mdx"
-            ./tools/parse.sh ${TEMPDIR} "${COMMAND}" $WEIGHT >"${FILE}"
-            if git diff "${FILE}" >/dev/null
-            then
-                DIFFS=true
-            fi
-            WEIGHT=$(expr $WEIGHT + 10)
-        else
-            while read SUBCOMMAND
-            do
-                FILE="${VERSIONED_DOCS}/oras_${COMMAND}_${SUBCOMMAND}.mdx"
-                ./tools/parse.sh ${TEMPDIR} "${COMMAND} ${SUBCOMMAND}" $WEIGHT >"${FILE}"
-                if git diff "${FILE}" >/dev/null
-                then
-                    DIFFS=true
-                fi
-                WEIGHT=$(expr $WEIGHT + 10)
-            done <"${TEMPDIR}/subcommands"
-        fi
-    done <"${TEMPDIR}/commands"
+    oras help | ./tools/parse_main.sh >"${VERSIONED_DOCS}/use_oras_cli.mdx"
+    ./tools/subcommands.sh "" "${VERSIONED_DOCS}"
 done
-if $DIFFS
-then
-    echo
-    echo '** Command generator made updates **'
-    echo
-fi

tools/subcommands.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+COMMAND="${1?First argument is command}"
+DESTINATION="${2?Second argument is destination directory}"
+
+TEMPDIR=$(mktemp -d)
+trap 'rm -rf "$TEMPDIR"' EXIT
+WEIGHT_FILE="${3}"
+if [ "${WEIGHT_FILE}" == "" ]
+then
+    WEIGHT_FILE="${3:-${TEMPDIR}/weight}"
+    echo 10 >${WEIGHT_FILE}
+fi
+
+./tools/list_commands.sh  "${COMMAND}" "${DESTINATION}" >"${TEMPDIR}/subcommands"
+if [ ! -s "${TEMPDIR}/subcommands" ]
+then
+    WEIGHT=$(cat $WEIGHT_FILE)
+    FILE="${DESTINATION}/oras_$(echo ${COMMAND} | sed -e 's/ /_/g').mdx"
+    ./tools/parse.sh "${COMMAND}" "$WEIGHT" >"${FILE}"
+    if ! git diff --quiet "${FILE}"
+    then
+        echo "** Updated ${FILE} **"
+    fi
+    echo $(expr $WEIGHT + 10) >${WEIGHT_FILE}
+    exit 0
+fi
+while read SUBCOMMAND
+do
+    ./tools/subcommands.sh "$(echo ${COMMAND} ${SUBCOMMAND})" "${DESTINATION}" "${WEIGHT_FILE}"
+done <"${TEMPDIR}/subcommands"

vale/config/vocabularies/oras/accept.txt

@@ -33,6 +33,7 @@ signoff
 [Ss]kippable
 Snapcraft
 stdin
+stdout
 [Ss]ubproject
 subprojects
 unencrypted

versioned_docs/version-1.3.0-beta.1/client_libraries/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Client Libraries",
+    "position": 40,
+    "link": {
+        "type": "generated-index",
+        "description": "The following languages are currently supported:"
+    }
+}

versioned_docs/version-1.3.0-beta.1/client_libraries/go.mdx

@@ -0,0 +1,55 @@
+---
+title: Go
+sidebar_position: 1
+---
+
+# Go
+
+Source code: [github.com/oras-project/oras-go](https://github.com/oras-project/oras-go)
+
+## Introduction
+
+The ORAS Go client library provides the ability to replicate artifacts between different [Targets](./overview.mdx#target).  
+Furthermore, the version `v2` is a registry client conforming [image-spec v1.1.0-rc6](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0-rc6) and [distribution-spec v1.1.0-rc4](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc4).
+
+Using the ORAS Go client library, you can develop your own registry client:
+
+```sh
+myclient push artifacts.example.com/myartifact:1.0 ./mything.thang
+```
+
+## Usage
+
+The package `oras.land/oras-go/v2` can quickly be imported in other Go-based tools that
+wish to benefit from the ability to store arbitrary content in container registries.
+
+1. Get the  `oras.land/oras-go/v2` package
+```sh
+go get oras.land/oras-go/v2
+```
+
+2. Import and use the `v2` package
+```go
+import "oras.land/oras-go/v2"
+```
+
+3. Run
+```sh
+go mod tidy
+```
+
+**The API documentation and examples are available at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2).**
+
+## Quick Start
+
+### Push files to a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PushFilesToRemoteRepository).
+
+### Pull files from a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullFilesFromRemoteRepository).
+
+### Pull a docker or OCI image from a remote repository
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageFromRemoteRepository).
+
+### Pull an Image using the Docker credential store
+See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageUsingDockerCredentials).