From ac9386723412e8d929a5c6e1722177ac9f540088 Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Fri, 28 Jan 2011 12:05:36 -0800 Subject: [PATCH] Start fleshing out docs. Yay planes to help you focus. --- website/content/cmd/camget | 10 +++++++ website/content/cmd/camput | 9 ++++++ website/content/cmd/index.html | 4 +++ website/content/contributors | 2 ++ website/content/docs/arch | 3 ++ website/content/docs/contributing | 12 ++++++++ website/content/docs/index.html | 27 ++++++++++++++++-- website/content/docs/json-signing | 15 ++++++++++ website/content/docs/prior-art | 12 ++++++++ website/content/docs/schema | 20 +++++++++++++ website/content/docs/sharing | 3 ++ website/content/docs/status | 47 +++++++++++++++++++++++++++++++ website/content/docs/terms | 33 ++++++++++++++++++++++ website/content/docs/uses | 22 +++++++++++++++ website/content/index.html | 10 +++---- website/static/all.css | 25 ++++++++++++++++ 16 files changed, 246 insertions(+), 8 deletions(-) create mode 100644 website/content/cmd/camget create mode 100644 website/content/cmd/camput create mode 100644 website/content/cmd/index.html create mode 100644 website/content/docs/arch create mode 100644 website/content/docs/contributing create mode 100644 website/content/docs/json-signing create mode 100644 website/content/docs/prior-art create mode 100644 website/content/docs/schema create mode 100644 website/content/docs/sharing create mode 100644 website/content/docs/status create mode 100644 website/content/docs/terms create mode 100644 website/content/docs/uses diff --git a/website/content/cmd/camget b/website/content/cmd/camget new file mode 100644 index 000000000..b49a487f7 --- /dev/null +++ b/website/content/cmd/camget @@ -0,0 +1,10 @@ +

camget

+ +

[code]

+ +

A tool to fetch files, blobs and objects from a blob server.

+ +

Usage

+ +... + diff --git a/website/content/cmd/camput b/website/content/cmd/camput new file mode 100644 index 000000000..725dab3f7 --- /dev/null +++ b/website/content/cmd/camput @@ -0,0 +1,9 @@ +

camput

+ +

[code]

+ +

A tool to put files, blobs and objects into a blob server.

+ +

Usage

+ +... diff --git a/website/content/cmd/index.html b/website/content/cmd/index.html new file mode 100644 index 000000000..2d6340c67 --- /dev/null +++ b/website/content/cmd/index.html @@ -0,0 +1,4 @@ + diff --git a/website/content/contributors b/website/content/contributors index a82fa1f7b..a8f0b6e12 100644 --- a/website/content/contributors +++ b/website/content/contributors @@ -11,3 +11,5 @@
  • Andrew Gerrand
    • +

    Want to help? See contributing.

    + diff --git a/website/content/docs/arch b/website/content/docs/arch new file mode 100644 index 000000000..ebd4160ae --- /dev/null +++ b/website/content/docs/arch @@ -0,0 +1,3 @@ +

    Architecture

    + +TODO diff --git a/website/content/docs/contributing b/website/content/docs/contributing new file mode 100644 index 000000000..1ebe5a2c7 --- /dev/null +++ b/website/content/docs/contributing @@ -0,0 +1,12 @@ +

    Contributing

    + +

    Want to contribute to the project? Awesome! + +

    + + diff --git a/website/content/docs/index.html b/website/content/docs/index.html index 2e20c30fc..77a5ac929 100644 --- a/website/content/docs/index.html +++ b/website/content/docs/index.html @@ -1,6 +1,27 @@ -

    Docs

    +

    Documentation

    -

    Most documentation is currently in the git docs/ directory.

    +

    Most documentation is currently in the +project's doc/ directory or in the source +itself. Some is now being promoted to HTML, though:

    + +

    Misc

    + + + +

    Commands

    + + -

    TODO: put more docs here

    diff --git a/website/content/docs/json-signing b/website/content/docs/json-signing new file mode 100644 index 000000000..1a87c8799 --- /dev/null +++ b/website/content/docs/json-signing @@ -0,0 +1,15 @@ +

    JSON Signing

    + +

    Some Camlistore JSON blobs are signed.

    + +

    Background & spec

    +

    See doc/json-signing/json-signing.txt in the git repo.

    + +

    Libraries

    + + + + + diff --git a/website/content/docs/prior-art b/website/content/docs/prior-art new file mode 100644 index 000000000..94a3d4988 --- /dev/null +++ b/website/content/docs/prior-art @@ -0,0 +1,12 @@ +

    Prior Art

    + +

    Other inspirational projects:

    + + + +

    TODO: flesh out this page

    + + diff --git a/website/content/docs/schema b/website/content/docs/schema new file mode 100644 index 000000000..017604510 --- /dev/null +++ b/website/content/docs/schema @@ -0,0 +1,20 @@ +

    Schema

    + +

    At the lowest layer Camlistore doesn't care what you put in it +(everything is just dumb bytes) and you're free to adopt your own data +model. However, the upper layers of Camlistore standardize on a common +schema to represent various classes of data.

    + +

    Here are some of the models we've started to formalize a JSON schema for:

    + + diff --git a/website/content/docs/sharing b/website/content/docs/sharing new file mode 100644 index 000000000..a6c887ec2 --- /dev/null +++ b/website/content/docs/sharing @@ -0,0 +1,3 @@ +

    Sharing

    + +.... diff --git a/website/content/docs/status b/website/content/docs/status new file mode 100644 index 000000000..63ff5190c --- /dev/null +++ b/website/content/docs/status @@ -0,0 +1,47 @@ +

    Status

    + +

    Camlistore has many pieces and many potential use cases. Here are some of the +pieces and use cases, and where they're at.

    + +

    Specification

    + + + + + +
    ItemStatusNotes
    Blob Server95%See doc/protocol/
    Sharing50%See mailing list thread "Example of sharing"
    + + +

    Servers

    + + + + + + + + + + + + + + + +
    ItemStatusNotes
    Blob Server (Local, Go)95%See server/go/blobserver
    Blob Server (Hosted, App Engine)95%See server/appengine/blobserver
    Blob Server test suite80%See server/tester/bs-test.pl
    Search / indexer server5%Toy prototype started. See indexing/basic. Upcoming area of focus.
    JSON signing / verification server (Go)80%See server/go/sigserver. Does JSON signing and verification, but doesn't yet permit uploading keys. This isn't a formal part of Camlistore but is rather a temporary bootstrapping component, a crutch for JavaScript.
    JSON signing / verification server (App Engine)70%See server/appengine/sigserver. Does JSON signing and verification, but doesn't yet permit uploading keys. This isn't a formal part of Camlistore but is rather a temporary bootstrapping component, a crutch for JavaScript.
    + +

    Tools

    + + + + + + + + +
    ItemStatusNotes
    camput50%the kitchen sink tool to inject content into a blobserver.
    camget10%tool to retrieve content from a blobserver.
    + +

    High-Level Use Cases

    +

    ... TODO: table for the various use cases.

    + diff --git a/website/content/docs/terms b/website/content/docs/terms new file mode 100644 index 000000000..59ffd034b --- /dev/null +++ b/website/content/docs/terms @@ -0,0 +1,33 @@ +

    Terminology

    + +

    To stay sane and communicate effectively we try hard to use +consistent terminology throughout the pieces of the project. Please let us know +if things here are confusing or lacking.

    + +
    + +
    blob
    +
    an immutable sequence of 0 or more bytes, with no extra metadata
    + +
    blobref
    +
    a reference to a blob, consisting of a cryptographic hash + function name and that hash function's digest of the blob's bytes, + in hex. Examples of valid blobrefs include: + 
    +     sha1-f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
+     md5-d3b07384d113edec49eaa6238ad5ff00
+     sha256-b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
    + Concatenating the two together with a hyphen is the common + representation, with both parts in all lower case. +
    + +
    blob server
    +
    the simplest and lowest layer of the Camlistore servers. A blob server, + while potentially shared between users, is logically private to a single user + and holds that user's blobs (whatever they may represent). + + + + + +
    diff --git a/website/content/docs/uses b/website/content/docs/uses new file mode 100644 index 000000000..6ef8332c3 --- /dev/null +++ b/website/content/docs/uses @@ -0,0 +1,22 @@ +

    Use Cases

    + +

    Camlistore is currently more of a vision than a product, but let us +at least lay out some of that vision here.

    + +

    What could one potentially do with all this?

    + + diff --git a/website/content/index.html b/website/content/index.html index d11fd450e..b2015a737 100644 --- a/website/content/index.html +++ b/website/content/index.html @@ -1,9 +1,9 @@ -

    What is Camlistore?

    +

    What is Camlistore?

    Camlistore is: