adding start of docs

.github/workflows/main.yaml

@@ -28,7 +28,7 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Environment
         run: conda create --quiet --name oras requests
-      - name: Test Oras Python (no auth)
+      - name: Test Oras Python
         env:
           registry_host: localhost
           registry_port: ${{ job.services.registry.ports[5000] }}

.github/workflows/release.yaml

@@ -0,0 +1,31 @@
+name: Release Python Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install
+      run: conda create --quiet --name oras twine
+
+    - name: Install dependencies
+      run: |
+        export PATH="/usr/share/miniconda/bin:$PATH"
+        source activate oras
+        pip install -e .
+        pip install setuptools wheel twine
+    - name: Build and publish
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USER }} 
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASS }}
+      run: |
+        export PATH="/usr/share/miniconda/bin:$PATH"
+        source activate oras
+        python setup.py sdist bdist_wheel
+        twine upload dist/*

README.md

@@ -4,159 +4,21 @@
 
 OCI Registry as Storage enables client libraries to push OCI Artifacts to [OCI Conformant](https://github.com/opencontainers/oci-conformance) registries. This is a Python client for that.
 
+See our ⭐️ [Documentation](https://oras-project.github.io/oras-py/) ⭐️ to get started.
 
-## Usage
-
-### Install
-
-You'll first need to install oras python! Either from pypi:
-
-```bash
-$ pip install oras
-```
-
-Or from a local clone:
-
-```bash
-$ git clone https://github.com/oras-project/oras-py
-$ cd oras-py
-$ pip install .
-```
-
-### Registry
-
-You should see [supported registries](https://oras.land/implementors/#docker-distribution), or if you
-want to deploy a local testing registry (without auth), you can do:
-
-```bash
-$ docker run -it --rm -p 5000:5000 ghcr.io/oras-project/registry:latest
-```
-
-To test token authentication, you can either [set up your own auth server](https://github.com/adigunhammedolalekan/registry-auth) 
-or just use an actual registry. The most we can do here is set up an example that uses basic auth.
-
-```bash
-# This is an htpassword file, "b" means bcrypt
-htpasswd -cB -b auth.htpasswd myuser mypass
-```
-
-The server below will work to login, but you won't be able to issue tokens.
-
-```bash
-# And start the registry with authentication
-docker run -it --rm -p 5000:5000 \
-    -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
-    -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
-    ghcr.io/oras-project/registry:latest
-```
-
-### Login
-
-Once you create (or already have) a registry, you will want to login. You can do:
-
-```bash
-$ oras-py login -u myuser -p mypass localhost:5000
-
-# or localhost (insecure)
-$ oras-py login -u myuser -p mypass -k localhost:5000 --insecure
-```
-```bash
-WARNING! Using --password via the CLI is insecure. Use --password-stdin.
-Login Succeeded
-```
-
-You can also provide them interactively
-
-```bash
-$ oras-py login -k localhost:5000 --insecure
-```
-```bash
-Username: myuser
-Password: mypass
-Login Succeeded
-```
-
-or use `--password-stdin`
-```bash
-$ echo mypass | oras-py login -u myuser -k localhost:5000 --insecure --password-stdin
-```
-```bash
-Login Succeeded
-```
-
-Note that oras-py will not remove content from your docker config files, so
-there is no concept of a "logout" unless you are using the client interactively,
-and have configs loaded, then you can do:
-
-```bash
-$ cli.logout(hostname)
-```
-
-### Push
-
-Let's first push a container. Let's follow [the example here](https://oras.land/cli/1_pushing/).
-
-```bash
-echo "hello dinosaur" > artifact.txt
-```
-```bash
-$ oras-py push localhost:5000/dinosaur/artifact:v1 \
---manifest-config /dev/null:application/vnd.acme.rocket.config \
-./artifact.txt
-```
-```bash
-Successfully pushed localhost:5000/dinosaur/artifact:v1
-```
-
-And if you aren't using https, add `--insecure`
-
-```bash
-$ oras-py push localhost:5000/dinosaur/artifact:v1 --insecure \
---manifest-config /dev/null:application/vnd.acme.rocket.config \
-./artifact.txt
-```
-```bash
-Successfully pushed localhost:5000/dinosaur/artifact:v1
-```
-
-### Pull
-
-Now try a pull! We will first need to delete the file
-
-```bash
-$ rm -f artifact.txt # first delete the file
-$ oras-py pull localhost:5000/dinosaur/artifact:v1
-```
-```bash
-$ cat artifact.txt
-hello dinosaur
-```
-
-### Docker Container
-
-We provide a [Dockerfile](Dockerfile) to build a container with the client.
-
-```bash
-$ docker build -t oras-py .
-```
-```bash
-$ docker run -it oras-py                                                                                                                   
-# which oras-py
-/opt/conda/bin/oras-py
-```
-
 ## TODO
 
  - add example (custom) GitHub client
  - refactor internals to be more like oras-go (e.g., provider, copy?)
  - need to have git commit, state, added to defaults on install/release. See [here](https://github.com/oras-project/oras/blob/main/Makefile).
- - plain_http, configs, need to be parsed in client
+ - plain_http vs insecure?
  - todo we haven't added path traversal, or cacheRoot to pull
  - environment variables like `ORAS_CACHE` 
 
 ## Code of Conduct
 
-This project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for further details.
+Please note that this project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
+Please follow it in all your interactions with the project members and users.
 
 ## License
 

docs/.gitignore

@@ -0,0 +1,2 @@
+_site
+Gemfile.lock

docs/Gemfile

@@ -0,0 +1,24 @@
+source "https://rubygems.org"
+ruby RUBY_VERSION
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "3.2.1"
+
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+# gem "minima"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", group: :jekyll_plugins
+
+# If you have any plugins, put them here!
+# group :jekyll_plugins do
+#   gem "jekyll-github-metadata", "~> 1.0"
+# end

docs/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2018-2019 Vanessa Sochat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/README.md

@@ -0,0 +1,45 @@
+# MkDocs Jekyll Theme
+
+[![CircleCI](https://circleci.com/gh/vsoch/mkdocs-jekyll/tree/master.svg?style=svg)](https://circleci.com/gh/vsoch/mkdocs-jekyll/tree/master)
+
+![https://raw.githubusercontent.com/vsoch/mkdocs-jekyll/master/assets/img/mkdocs-jekyll.png](https://raw.githubusercontent.com/vsoch/mkdocs-jekyll/master/assets/img/mkdocs-jekyll.png)
+
+This is a [starter template](https://vsoch.github.com/mkdocs-jekyll/) for a mkdocs jekyll theme, based on these two
+previous arts:
+
+ - [alexcarpenter/material-jekyll-theme](http://alexcarpenter.github.io/material-jekyll-theme)
+ - [squidfunk/mkdocs-material](https://github.com/squidfunk/mkdocs-material)
+
+## Usage
+
+### 1. Get the code
+
+You can clone the repository right to where you want to host the docs:
+
+```bash
+git clone https://github.com/vsoch/mkdocs-jekyll.git docs
+cd docs
+```
+
+### 2. Customize
+
+To edit configuration values, customize the [_config.yml](https://github.com/vsoch/mkdocs-jekyll/blob/master/_config.yml).
+To add pages, write them into the [pages](https://github.com/vsoch/mkdocs-jekyll/tree/master/pages) folder. 
+You define urls based on the `permalink` attribute in your pages,
+and then add them to the navigation by adding to the content of [_data/toc.myl](https://github.com/vsoch/mkdocs-jekyll/blob/master/_data/toc.yml).
+
+### 3. Options
+
+Most of the configuration values in the [_config.yml](https://github.com/vsoch/mkdocs-jekyll/blob/master/_config.yml) are self explanatory,
+and for more details, see the [about page](https://vsoch.github.io/mkdocs-jekyll/about/)
+rendered on the site.
+
+### 4. Serve
+
+Depending on how you installed jekyll:
+
+```bash
+jekyll serve
+# or
+bundle exec jekyll serve
+```

docs/VERSION

@@ -0,0 +1 @@
+0.0.17

docs/_config.yml

@@ -0,0 +1,70 @@
+title: Oras Python
+author: The Oras Authors
+description: > # this means to ignore newlines until "baseurl:"
+  Oras or OCI Registry As Storage makes it easy to push arbitrary artifacts
+  to an oras registry. This is the Python client.
+
+footer_description: We are a Cloud Native Computing Foundation sandbox project.
+baseurl: "/oras-py" # the subpath of your site, e.g. /blog
+url: "https://oras-project.github.io"
+
+# Social (First three Required)
+repo: "https://github.com/oras-project/oras-py"
+github_user: "oras-project"
+github_repo: "oras-py"
+
+# Optional
+twitter: orasproject
+logo: assets/img/oras.png
+logo_pixels: 34
+color: "#4051b5" # primary color for header, buttons
+
+# Build settings
+markdown: kramdown
+
+# If you add tags to pages, you can link them to some external search
+# If you want to disable this, comment the URL.
+# tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q=
+tag_color: primary # danger, success, warning, primary, info, secondary
+
+# Add a page at /forum to list a set of discourse topics. The site needs
+# to enable "embed topics" setting
+# https://meta.discourse.org/t/embedding-a-list-of-discourse-topics-in-another-site/125911
+# discourse_site: "https://ask.cyberinfrastructure.org" 
+# discourse_per_page: 10
+# discourse_category: "stanford-research-computing"
+# discourse_tags: null # comma separated string, leave null to not filter
+
+accentColor: blue # purple, green, etc.
+themeColor: blue # purple, green, blue, orange, purple, grey
+fixedNav: 'true' # true or false
+
+permalink: /:year/:title/
+markdown: kramdown
+exclude: [_site, CHANGELOG.md, LICENSE, README.md, vendor]
+
+# Collections
+collections:
+  docs:
+    output: true
+    permalink: /:collection/:path
+
+# Defaults
+defaults:
+  - scope:
+      path: "_docs"
+      type: "docs"
+    values:
+      layout: page
+  -
+    scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: "page"
+  -
+    scope:
+      path: "posts"
+      type: "posts"
+    values:
+      layout: "post"

docs/_data/toc.yml

@@ -0,0 +1,24 @@
+- title: "Getting Started"
+  url: "docs/getting-started"
+  children:
+    - title: User Guide
+      url: "docs/getting-started#usage"
+    - title: Login
+      url: "docs/getting-started#login"
+    - title: Push
+      url: "docs/getting-started#push"
+    - title: Pull
+      url: "docs/getting-started#pull"
+    - title: Docker Container
+      url: "docs/getting-started#docker-container"
+
+- title: "Contributing"
+  url: "docs/contributing"
+  children:
+    - title: Contribute to Code
+      url: "docs/contributing#code"
+    - title: Contributing to Docs
+      url: "docs/contributing#documentation"
+- title: "Oras Project Site"
+  external_url: https://oras.land
+