From 6b319b410b86470b39e4a8ebab6805970801b3d7 Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Sun, 20 Sep 2020 22:29:00 +0300 Subject: [PATCH] docs: Update README Signed-off-by: Stanislav Bogatyrev --- .github/logo.svg | 129 ++++++++++++++++++++++++++++++++++++ .github/markdown.tmpl | 83 ----------------------- README.md | 151 +++++------------------------------------- 3 files changed, 145 insertions(+), 218 deletions(-) create mode 100644 .github/logo.svg delete mode 100644 .github/markdown.tmpl diff --git a/.github/logo.svg b/.github/logo.svg new file mode 100644 index 0000000..b4da076 --- /dev/null +++ b/.github/logo.svg @@ -0,0 +1,129 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.github/markdown.tmpl b/.github/markdown.tmpl deleted file mode 100644 index f945c13..0000000 --- a/.github/markdown.tmpl +++ /dev/null @@ -1,83 +0,0 @@ -# Protocol Documentation - - -## Table of Contents -{{range .Files}} -{{$file_name := .Name}}- [{{.Name}}](#{{.Name}}) -{{if .Services}} - Services - {{range .Services}}- [{{.Name}}](#{{.FullName}}) - {{end}}{{end}} -{{if .Messages}} - Messages - {{range .Messages}}- [{{.LongName}}](#{{.FullName}}) - {{end}}{{end}} -{{end}} -- [Scalar Value Types](#scalar-value-types) - -{{range .Files}} -{{$file_name := .Name}} - -

Top

- -## {{.Name}} -{{.Description}} - -{{range .Services}} - - - -### Service "{{.FullName}}" -{{.Description}} - -``` -{{range .Methods -}} - rpc {{.Name}}({{if .RequestStreaming}}stream {{end}}{{.RequestLongType}}) returns ({{if .ResponseStreaming}}stream {{end}}{{.ResponseLongType}}); -{{end}} -``` - -{{range .Methods -}} -#### Method {{.Name}} - -{{.Description}} - -| Name | Input | Output | -| ---- | ----- | ------ | -| {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}) | [{{.ResponseLongType}}](#{{.ResponseFullType}}) | -{{end}}{{end}} - -{{range .Messages}} - - -### Message {{.LongName}} -{{.Description}} - -{{if .HasFields}} -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -{{range .Fields -}} - | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | -{{end}}{{end}} -{{end}} - -{{range .Enums}} - - -### {{.LongName}} -{{.Description}} - -| Name | Number | Description | -| ---- | ------ | ----------- | -{{range .Values -}} - | {{.Name}} | {{.Number}} | {{nobr .Description}} | -{{end}} - -{{end}} - -{{end}} - -## Scalar Value Types - -| .proto Type | Notes | C++ Type | Java Type | Python Type | -| ----------- | ----- | -------- | --------- | ----------- | -{{range .Scalars -}} - | {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | -{{end}} diff --git a/README.md b/README.md index 31c87f6..ca3684b 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,31 @@ -# NeoFS API +

+NeoFS +

+

+ Golang SDK for NeoFS +

+--- ![Go](https://github.com/nspcc-dev/neofs-api-go/workflows/Go/badge.svg) [![codecov](https://codecov.io/gh/nspcc-dev/neofs-api-go/branch/master/graph/badge.svg)](https://codecov.io/gh/nspcc-dev/neofs-api-go) [![Report](https://goreportcard.com/badge/github.com/nspcc-dev/neofs-api-go)](https://goreportcard.com/report/github.com/nspcc-dev/neofs-api-go) [![GitHub release](https://img.shields.io/github/release/nspcc-dev/neofs-api.svg)](https://github.com/nspcc-dev/neofs-api-go) ![GitHub license](https://img.shields.io/github/license/nspcc-dev/neofs-api.svg?style=popout) ---- +# Overview -NeoFS API repository contains implementation of core NeoFS structures that -can be used for integration with NeoFS. - -## Сompatibility - -[neofs-api v1.1.0]: https://github.com/nspcc-dev/neofs-api/releases/tag/v1.1.0 -[neofs-api-go v1.1.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.1.0 -* [neofs-api-go v1.1.0] supports [neofs-api v1.1.0] - -[neofs-api v1.2.0]: https://github.com/nspcc-dev/neofs-api/releases/tag/v1.2.0 -[neofs-api-go v1.2.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.2.0 -* [neofs-api-go v1.2.0] supports [neofs-api v1.2.0] - -[neofs-api-go v1.3.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.3.0 -* [neofs-api-go v1.3.0] supports [neofs-api v1.2.0] - -## Description - -Repository contains 13 packages that implement NeoFS core structures. These -packages mostly contain protobuf files with service and structure definitions -or NeoFS core types with complemented functions. - -There is a auto-generated documentation for protobuf files in [docs](docs). - -### Accounting - -Accounting package defines services and structures for accounting operations: -balance request and `cheque` operations for withdraw. `Cheque` is a structure -with inner ring signatures, which approve that user can withdraw requested -amount of assets. NeoFS smart contract takes binary formatted `cheque` as a -parameter in withdraw call. - -#### API -Accounting package defines: -- [Accounting service](docs/accounting.md#accounting.Accounting) -- [Withdraw service](docs/accounting.md#accounting.Withdraw) - - -### Bootstrap - -Bootstrap package defines bootstrap service which is used by storage nodes to -connect to the storage network. - -#### API -Bootstrap package defines: -- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap) - - -### Chain - -Chain package contains util functions for operations with NEO Blockchain types: -wallet addresses, script-hashes. - -### Container - -Container package defines service and structures for operations with containers. -Objects in NeoFS are stored in containers. Container defines storage -policy for the objects. - -#### API -Bootstrap package defines: -- [Container service](docs/container.md#container.Service) - -### Decimal - -Decimal defines custom decimal implementation which is used in accounting -operations. - -### Hash - -Hash package defines homomorphic hash type. - -### Internal - -Internal package defines constant error type and proto interface for custom -protobuf structures. - -### Object - -Object package defines service and structures for object operations. Object is -a core storage structure in NeoFS. Package contains detailed information -about object internal structure. - -#### API -Object package defines: -- [Object service](docs/object.md#object.Service) - -### Query - -Query package defines structure for object search requests. - -### Refs - -Refs package defines core identity types: Object ID, Container ID, etc. - -### Service - -Service package defines util structure and functions for all NeoFS services -operations: TTL and request signature management, node roles, epoch retriever. - -### Session - -Session package defines service and structures for session obtain. Object -operations require an established session with pair of session keys signed by -owner of the object. - -#### API -Session package defines: -- [Session service](docs/session.md#session.Session) - -### State - -State package defines service and structures for metrics gathering. - -#### API -State package defines: -- [Status service](docs/state.md#state.Status) - -## How to use - -NeoFS API packages contain godoc documentation. Examples of using most of -these packages can be found in NeoFS-CLI repository. CLI implements and -demonstrates all basic interactions with NeoFS: container, object, storage -group, and accounting operations. - -Protobuf files are recompiled with the command: - -``` -$ make protoc -``` +Go implementation of recent [NeoFS API](https://github.com/nspcc-dev/neofs-api) +versions and SDK layer working with all of them in a handy way. ## Contributing -At this moment, we do not accept contributions. +Feel free to contribute to this project after reading the [contributing +guidelines](CONTRIBUTING.md). + +Before starting to work on a certain topic, create an new issue first, +describing the feature/topic you are going to implement. ## License -This project is licensed under the Apache 2.0 License - +This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details -