add protobuf documentation

2026-03-13 04:37:46 -04:00 · 2020-03-26 11:25:57 +01:00
parent 01672d1da5
commit 336565fe24
5 changed files with 259 additions and 43 deletions
--- a/52
+++ b/52
@@ -4,6 +4,8 @@ IMPORT := github.com/owncloud/$(NAME)
 BIN := bin
 DIST := dist
 HUGO := hugo
+PROTO_VERSION := v0
+PROTO_SRC := pkg/proto/$(PROTO_VERSION)/*.proto

 ifeq ($(OS), Windows_NT)
 	EXECUTABLE := $(NAME).exe
@@ -131,6 +133,11 @@ release-check:
 .PHONY: release-finish
 release-finish: release-copy release-check

+.PHONY: proto-docs-build
+proto-docs-build:
+	go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc; \
+	protoc --doc_out=./docs --doc_opt=./docs/grpc.tmpl,grpc.md $(PROTO_SRC)
+
 .PHONY: docs-copy
 docs-copy:
 	mkdir -p $(HUGO); \
@@ -141,54 +148,19 @@ docs-copy:
 	git remote add origin https://github.com/owncloud/owncloud.github.io; \
 	git fetch; \
 	git checkout origin/source -f; \
-	rsync --delete -ax ../docs/ content/extensions/$(NAME)
+	rsync --delete -ax ../docs/*.md content/extensions/$(NAME)

 .PHONY: docs-build
 docs-build:
 	cd $(HUGO); hugo

 .PHONY: docs
-docs: docs-copy docs-build
+docs: proto-docs-build docs-copy docs-build

 .PHONY: watch
 watch:
 	go run github.com/cespare/reflex -c reflex.conf

-# $(GOPATH)/bin/protoc-gen-go:
-# 	GO111MODULE=off go get -v github.com/golang/protobuf/protoc-gen-go
-
-# $(GOPATH)/bin/protoc-gen-micro:
-# 	GO111MODULE=off go get -v github.com/micro/protoc-gen-micro
-
-# $(GOPATH)/bin/protoc-gen-microweb:
-# 	GO111MODULE=off go get -v github.com/webhippie/protoc-gen-microweb
-
-# $(GOPATH)/bin/protoc-gen-swagger:
-# 	GO111MODULE=off go get -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
-
-# pkg/proto/v0/example.pb.go: pkg/proto/v0/example.proto
-# 	protoc \
-# 		-I=third_party/ \
-# 		-I=pkg/proto/v0/ \
-# 		--go_out=logtostderr=true:pkg/proto/v0 example.proto
-
-# pkg/proto/v0/example.pb.micro.go: pkg/proto/v0/example.proto
-# 	protoc \
-# 		-I=third_party/ \
-# 		-I=pkg/proto/v0/ \
-# 		--micro_out=logtostderr=true:pkg/proto/v0 example.proto
-
-# pkg/proto/v0/example.pb.web.go: pkg/proto/v0/example.proto
-# 	protoc \
-# 		-I=third_party/ \
-# 		-I=pkg/proto/v0/ \
-# 		--microweb_out=logtostderr=true:pkg/proto/v0 example.proto
-
-# pkg/proto/v0/example.swagger.json: pkg/proto/v0/example.proto
-# 	protoc \
-# 		-I=third_party/ \
-# 		-I=pkg/proto/v0/ \
-# 		--swagger_out=logtostderr=true:pkg/proto/v0 example.proto
-
-# .PHONY: protobuf
-# protobuf:  $(GOPATH)/bin/protoc-gen-go $(GOPATH)/bin/protoc-gen-micro $(GOPATH)/bin/protoc-gen-microweb $(GOPATH)/bin/protoc-gen-swagger pkg/proto/v0/example.pb.go pkg/proto/v0/example.pb.micro.go pkg/proto/v0/example.pb.web.go pkg/proto/v0/example.swagger.json
+.PHONY: pb
+pb:
+	protoc --go_out=. --micro_out=. $(PROTO_SRC)
--- a/docs/grpc.md
+++ b/docs/grpc.md
@@ -0,0 +1,119 @@
+---
+title: "GRPC API"
+date: 2018-05-02T00:00:00+00:00
+weight: 40
+geekdocRepo: https://github.com/owncloud/ocis-thumbnails
+geekdocEditPath: edit/master/docs
+geekdocFilePath: grpc.md
+---
+
+<a name="top"></a>
+
+## Table of Contents
+
+- [pkg/proto/v0/thumbnails.proto](#pkg/proto/v0/thumbnails.proto)
+    - [GetRequest](#com.owncloud.ocis.thumbnails.v0.GetRequest)
+    - [GetResponse](#com.owncloud.ocis.thumbnails.v0.GetResponse)
+  
+    - [GetRequest.FileType](#com.owncloud.ocis.thumbnails.v0.GetRequest.FileType)
+  
+    - [ThumbnailService](#com.owncloud.ocis.thumbnails.v0.ThumbnailService)
+  
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="pkg/proto/v0/thumbnails.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## pkg/proto/v0/thumbnails.proto
+
+
+
+<a name="com.owncloud.ocis.thumbnails.v0.GetRequest"></a>
+
+### GetRequest
+A request to retrieve a thumbnail
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| filepath | [string](#string) |  | The path to the source image |
+| filetype | [GetRequest.FileType](#com.owncloud.ocis.thumbnails.v0.GetRequest.FileType) |  | The type to which the thumbnail should get encoded to. |
+| etag | [string](#string) |  | The etag of the source image |
+| width | [int32](#int32) |  | The width of the thumbnail |
+| height | [int32](#int32) |  | The height of the thumbnail |
+| authorization | [string](#string) |  | The authorization token |
+
+
+
+
+
+
+<a name="com.owncloud.ocis.thumbnails.v0.GetResponse"></a>
+
+### GetResponse
+The service response
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| thumbnail | [bytes](#bytes) |  | The thumbnail as a binary |
+| mimetype | [string](#string) |  | The mimetype of the thumbnail |
+
+
+
+
+
+ <!-- end messages -->
+
+
+<a name="com.owncloud.ocis.thumbnails.v0.GetRequest.FileType"></a>
+
+### GetRequest.FileType
+The file types to which the thumbnail cna get encoded to.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| PNG | 0 | Represents PNG type |
+| JPG | 1 | Represents JPG type |
+
+
+ <!-- end enums -->
+
+ <!-- end HasExtensions -->
+
+
+<a name="com.owncloud.ocis.thumbnails.v0.ThumbnailService"></a>
+
+### ThumbnailService
+A Service for handling thumbnail generation
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+| GetThumbnail | [GetRequest](#com.owncloud.ocis.thumbnails.v0.GetRequest) | [GetResponse](#com.owncloud.ocis.thumbnails.v0.GetResponse) | Generates the thumbnail and returns it. |
+
+ <!-- end services -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
+| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
+| <a name="double" /> double |  | double | double | float | float64 | double | float | Float |
+| <a name="float" /> float |  | float | float | float | float32 | float | float | Float |
+| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="bool" /> bool |  | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |
+
--- a/docs/grpc.tmpl
+++ b/docs/grpc.tmpl
@@ -0,0 +1,112 @@
+---
+title: "GRPC API"
+date: 2018-05-02T00:00:00+00:00
+weight: 40
+geekdocRepo: https://github.com/owncloud/ocis-thumbnails
+geekdocEditPath: edit/master/docs
+geekdocFilePath: grpc.md
+---
+
+<a name="top"></a>
+
+## Table of Contents
+{{range .Files}}
+{{$file_name := .Name}}- [{{.Name}}](#{{.Name}})
+  {{- if .Messages }}
+  {{range .Messages}}  - [{{.LongName}}](#{{.FullName}})
+  {{end}}
+  {{- end -}}
+  {{- if .Enums }}
+  {{range .Enums}}  - [{{.LongName}}](#{{.FullName}})
+  {{end}}
+  {{- end -}}
+  {{- if .Extensions }}
+  {{range .Extensions}}  - [File-level Extensions](#{{$file_name}}-extensions)
+  {{end}}
+  {{- end -}}
+  {{- if .Services }}
+  {{range .Services}}  - [{{.Name}}](#{{.FullName}})
+  {{end}}
+  {{- end -}}
+{{end}}
+- [Scalar Value Types](#scalar-value-types)
+
+{{range .Files}}
+{{$file_name := .Name}}
+<a name="{{.Name}}"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## {{.Name}}
+{{.Description}}
+
+{{range .Messages}}
+<a name="{{.FullName}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+{{if .HasFields}}
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+{{range .Fields -}}
+  | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+{{end}}
+{{end}}
+
+{{if .HasExtensions}}
+| Extension | Type | Base | Number | Description |
+| --------- | ---- | ---- | ------ | ----------- |
+{{range .Extensions -}}
+  | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+{{end}}
+{{end}}
+
+{{end}} <!-- end messages -->
+
+{{range .Enums}}
+<a name="{{.FullName}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+  | {{.Name}} | {{.Number}} | {{nobr .Description}} |
+{{end}}
+
+{{end}} <!-- end enums -->
+
+{{if .HasExtensions}}
+<a name="{{$file_name}}-extensions"></a>
+
+### File-level Extensions
+| Extension | Type | Base | Number | Description |
+| --------- | ---- | ---- | ------ | ----------- |
+{{range .Extensions -}}
+  | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}} |
+{{end}}
+{{end}} <!-- end HasExtensions -->
+
+{{range .Services}}
+<a name="{{.FullName}}"></a>
+
+### {{.Name}}
+{{.Description}}
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+{{range .Methods -}}
+  | {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType}}){{if .ResponseStreaming}} stream{{end}} | {{nobr .Description}} |
+{{end}}
+{{end}} <!-- end services -->
+
+{{end}}
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
+| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
+{{range .Scalars -}}
+  | <a name="{{.ProtoType}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} |
+{{end}}
--- a/docs/license.md
+++ b/docs/license.md
@@ -1,7 +1,7 @@
 ---
 title: "License"
 date: 2018-05-02T00:00:00+00:00
-weight: 40
+weight: 50
 geekdocRepo: https://github.com/owncloud/ocis-thumbnails
 geekdocEditPath: edit/master/docs
 geekdocFilePath: license.md
--- a/pkg/proto/v0/thumbnails.proto
+++ b/pkg/proto/v0/thumbnails.proto
@@ -3,24 +3,37 @@ syntax = "proto3";
 package com.owncloud.ocis.thumbnails.v0;
 option go_package = "proto";

+// A Service for handling thumbnail generation
 service ThumbnailService {
+    // Generates the thumbnail and returns it.
    rpc GetThumbnail(GetRequest) returns (GetResponse);
 }

+// A request to retrieve a thumbnail
 message GetRequest {
+    // The path to the source image
    string filepath = 1;
+    // The file types to which the thumbnail cna get encoded to.
    enum FileType {
-        PNG = 0;
-        JPG = 1;
+        PNG = 0; // Represents PNG type
+        JPG = 1; // Represents JPG type
    }
+    // The type to which the thumbnail should get encoded to.
    FileType filetype = 2;
+    // The etag of the source image
    string etag = 3;
+    // The width of the thumbnail
    int32 width = 4;
+    // The height of the thumbnail
    int32 height = 5;
+    // The authorization token
    string authorization = 6;
 }

+// The service response
 message GetResponse {
+    // The thumbnail as a binary
    bytes thumbnail = 1;
+    // The mimetype of the thumbnail
    string mimetype = 2;
 }