docs: add proto file documentation in markdown (#31)

CONTRIBUTING.md

@@ -218,6 +218,13 @@ When creating interfaces with the need to generate mocks, you must add the follo
 //go:generate mockgen -destination=<path_to_mocks>/mock_<file>.go -package=mocks -source=<file>.go
 ```
 
+## Documentation
+
+If you made any changes in the `.proto` file, you must generate the documentation with the following command:
+```shell
+make gen-docs
+```
+
 ## Docker Image
 
 To generate the Deckard image we use the [ko](https://github.com/google/ko) tool.

Makefile

@@ -69,6 +69,12 @@ gen-mocks:
 
 	go generate ./...
 
+gen-docs:
+# https://github.com/pseudomuto/protoc-gen-doc/pull/520 or https://github.com/pseudomuto/protoc-gen-doc/pull/486
+	@if ! command -v protoc-gen-doc > /dev/null; then echo "Installing protoc-gen-doc" && go install -a -v github.com/lucasoares/protoc-gen-doc/cmd/protoc-gen-doc@change-module-name; fi;
+
+	protoc --doc_out=./docs/ --doc_opt=docs/markdown.tmpl,proto.md proto/*
+
 # Generate certificates for tests
 gen-cert:
 	cd internal/service/cert; ./gen.sh 2>/dev/null || echo "ERROR: Certificate generation failed"

docs/getting-started.md

@@ -2,9 +2,24 @@
 
 This guide will help you to start using Deckard and consists of the following sections:
 
+- [Understanding Deckard](#understanding-deckard)
 - [Running Deckard](#running-deckard)
 - [Consuming Deckard](#consuming-deckard)
 
+## Understanding Deckard
+
+Deckard is a priority queue that uses gRPC to communicate with its clients.
+
+To learn more about its components please check the [components documentation](components.md).
+
+To check the available configuration options please check the [configuration section](/README.md?#configuration).
+
+To learn the structure of this git project and its folders, check the [contributing guide](/CONTRIBUTING.md).
+
+To learn how to integrate Deckard with your application please check [consuming section](#consuming-deckard).
+
+To understand which services are exposed by Deckard and its message and types, please check the documentation of Deckard's [protocol buffer definition](proto.md).
+
 ## Running Deckard
 
 The fastest way to start using deckard is by using Docker or downloading its binary.
@@ -65,7 +80,7 @@ Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force
 
 ## Consuming Deckard
 
-Deckard exposes a gRPC service that can be consumed by any gRPC client. You can find the proto file [here](/proto/deckard_service.proto).
+Deckard exposes a gRPC service that can be consumed by any gRPC client. You can find a documentation of the exposed service, messages and types [here](proto.md). Deckard contains a single proto file and it is located [here](/proto/deckard_service.proto).
 
 We suggest the usage of [Postman](https://www.postman.com/) to consume the gRPC service manually. You can follow the steps below to configure Postman to consume the gRPC service:
 

docs/markdown.tmpl

@@ -0,0 +1,96 @@
+# Protocol Documentation
+<a name="top"></a>
+
+{{range .Files}}
+
+{{.Description}}
+
+{{range .Services}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.Name}} Service
+{{.Description}}
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+{{range .Methods -}}
+  | {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType | anchor}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType | anchor}}){{if .ResponseStreaming}} stream{{end}} | {{br .Description}} |
+{{end}}
+{{end}} <!-- end services -->
+
+## Messages
+
+{{range .Messages}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+{{if .HasFields}}
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+{{range .Fields -}}
+  | {{.Name}} | [{{.LongType}}](#{{.FullType | anchor}}) | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{br .Description}}{{if .DefaultValue}}<br/><br/>Default: {{.DefaultValue}}{{end}} |
+{{end}}
+{{end}}
+
+{{if .HasExtensions}}
+| Extension | Type | Base | Number | Description |
+| --------- | ---- | ---- | ------ | ----------- |
+{{range .Extensions -}}
+  | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{br .Description}}{{if .DefaultValue}}<br/><br/>Default: {{.DefaultValue}}{{end}} |
+{{end}}
+{{end}}
+
+{{end}} <!-- end messages -->
+
+{{range .Enums}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+  | {{.Name}} | {{.Number}} | {{br .Description}} |
+{{end}}
+
+{{end}} <!-- end enums -->
+
+{{if .HasExtensions}}
+<a name="extensions"></a>
+
+### File-level Extensions
+| Extension | Type | Base | Number | Description |
+| --------- | ---- | ---- | ------ | ----------- |
+{{range .Extensions -}}
+  | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{br .Description}}{{if .DefaultValue}}<br/><br/>Default: `{{.DefaultValue}}`{{end}} |
+{{end}}
+{{end}} <!-- end HasExtensions -->
+
+{{end}}
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
+| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
+{{range .Scalars -}}
+  | <a name="{{.ProtoType | anchor}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} |
+{{end}}
+
+## Google Protobuf Any
+
+The Any type is a special type that can represent any other type.
+
+The Any message type lets you use messages as embedded types without having their .proto definition. 
+An Any contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type.
+
+Documentation on how to use this field for each language:
+- [C++](https://protobuf.dev/reference/cpp/cpp-generated/#any)
+- [Java](https://protobuf.dev/reference/java/java-generated/#any)
+- [Python](https://protobuf.dev/reference/python/python-generated/#any)
+- [Go](https://pkg.go.dev/google.golang.org/protobuf/types/known/anypb)
+- [C#](https://learn.microsoft.com/en-us/dotnet/architecture/grpc-for-wcf-developers/protobuf-any-oneof#any)
+- [PHP](https://github.com/protocolbuffers/protobuf/blob/main/php/src/Google/Protobuf/Any.php)
+- [Ruby](https://cloud.google.com/ruby/docs/reference/google-cloud-container_analysis-v1/latest/Google-Protobuf-Any)