Skip to content
This repository has been archived by the owner on Mar 4, 2022. It is now read-only.

Start adding long help documentation strings #152

Merged
merged 7 commits into from
Jul 25, 2018
Merged

Start adding long help documentation strings #152

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0f95d78
Start work on longer help docs
bufdev Jul 16, 2018
d407f28
Use wordwrap
bufdev Jul 16, 2018
d7403ea
Create
bufdev Jul 16, 2018
de180aa
gRPC
bufdev Jul 16, 2018
d5b4cf6
various nits
peats-bond Jul 16, 2018
1d3c61b
actually make `wordWrapLength` a const :/
peats-bond Jul 16, 2018
54ca147
remove filedescriptorset from gRPC help
peats-bond Jul 18, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions glide.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions glide.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import:
- package: github.com/gogo/protobuf/protoc-gen-gogoslick
- package: github.com/golang/protobuf/protoc-gen-go
- package: github.com/jhump/protoreflect/dynamic
- package: github.com/mitchellh/go-wordwrap
- package: github.com/spf13/cobra
- package: github.com/spf13/pflag
- package: go.uber.org/atomic
Expand Down
148 changes: 146 additions & 2 deletions internal/cmd/templates.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,18 @@ import (
"fmt"
"io"
"os"
"strings"

wordwrap "github.com/mitchellh/go-wordwrap"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
"github.com/uber/prototool/internal/exec"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)

const wordWrapLength uint = 80

var (
allCmdTemplate = &cmdTemplate{
Use: "all dirOrProtoFiles...",
Expand Down Expand Up @@ -71,6 +75,7 @@ var (
compileCmdTemplate = &cmdTemplate{
Use: "compile dirOrProtoFiles...",
Short: "Compile with protoc to check for failures.",
Long: `Stubs will not be generated. To generate stubs, use the "gen" command. Calling "compile" has the effect of calling protoc with "-o /dev/null".`,
Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.Compile(args, flags.dryRun)
},
Expand All @@ -83,6 +88,62 @@ var (
createCmdTemplate = &cmdTemplate{
Use: "create files...",
Short: "Create the given Protobuf files according to a template that passes default prototool lint.",
Long: `Assuming the filename "example_create_file.proto", the file will look like the following:

syntax = "proto3";

package SOME.PKG;

option go_package = "PKGpb";
option java_multiple_files = true;
option java_outer_classname = "ExampleCreateFileProto";
option java_package = "com.SOME.PKG.pb";

This matches what the linter expects. "SOME.PKG" will be computed as follows:

- If "--package" is specified, "SOME.PKG" will be the value passed to
"--package".
- Otherwise, if there is no "prototool.yaml" that would apply to the new file,
use "uber.prototool.generated".
- Otherwise, if there is a "prototool.yaml" file, check if it has a
"dir_to_base_package" setting under the "create" section. If it does, this
package, concatenated with the relative path from the directory with the
"prototool.yaml" will be used.
- Otherwise, if there is no "dir_to_base_package" directive, just use the
relative path from the directory with the "prototool.yaml" file. If the file
is in the same directory as the "prototoo.yaml" file, use
"uber.prototool.generated".

For example, assume you have the following file at "repo/prototool.yaml":

create:
dir_to_base_package:
idl: uber
idl/baz: special

- "prototool create repo/idl/foo/bar/bar.proto" will have the package
"uber.foo.bar".
- "prototool create repo/idl/bar.proto" will have the package "uber".
- "prototool create repo/idl/baz/baz.proto" will have the package "special".
- "prototool create repo/idl/baz/bat/bat.proto" will have the package
"special.bat".
- "prototool create repo/another/dir/bar.proto" will have the package
"another.dir".
- "prototool create repo/bar.proto" will have the package
"uber.prototool.generated".

This is meant to mimic what you generally want - a base package for your idl directory, followed by packages matching the directory structure.

Note you can override the directory that the "prototool.yaml" file is in as well. If we update our file at "repo/prototool.yaml" to this:

create:
dir_to_base_package:
.: foo.bar

Then "prototool create repo/bar.proto" will have the package "foo.bar", and "prototool create repo/another/dir/bar.proto" will have the package "foo.bar.another.dir".

If Vim integration is set up, files will be generated when you open a new Protobuf file.`,

Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.Create(args, flags.pkg)
},
Expand Down Expand Up @@ -135,6 +196,7 @@ var (
formatCmdTemplate = &cmdTemplate{
Use: "format dirOrProtoFiles...",
Short: "Format a proto file and compile with protoc to check for failures.",
Long: `By default, the values for "java_multiple_files", "java_outer_classname", and "java_package" are updated to reflect what is expected by the Google Cloud APIs file structure at https://cloud.google.com/apis/design/file_structure, and the value of "go_package" is updated to reflect what we expect for the default Style Guide. By formatting, the linting for these values will pass by default. See the documentation for "create" for an example. This functionality can be suppressed by passing the flag "--no-rewrite".`,
Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.Format(args, flags.overwrite, flags.diffMode, flags.lintMode, !flags.noRewrite)
},
Expand All @@ -161,6 +223,86 @@ var (
grpcCmdTemplate = &cmdTemplate{
Use: "grpc dirOrProtoFiles...",
Short: "Call a gRPC endpoint. Be sure to set required flags address, method, and either data or stdin.",
Long: `What this does behind the scenes:

- Compiles your Protobuf files with "protoc", generating a "FileDescriptorSet".
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this part may be unnecessary, describing a FileDescriptorSet. What if we simplified it as:

This command compiles your proto files with "protoc", converts JSON input to binary
and converts the result from binary to JSON. All these steps take on the order of 
milliseconds. For example, the overhead for a file with four dependencies is about
30ms, so there is little overhead for CLI calls to gRPC.

Commenting here to get both your thoughts, not sure if this is any clearer.

- Uses the "FileDescriptorSet" to figure out the request and response type for
the endpoint, and to convert the JSON input to binary.
- Calls the gRPC endpoint.
- Uses the "FileDescriptorSet" to convert the resulting binary back to JSON,
and prints it out for you.

All these steps take on the order of milliseconds, for example the overhead for a file with four dependencies is about 30ms, so there is little overhead for CLI calls to gRPC.

There is a full example for gRPC in the example directory of Prototool. Run "make init example" to make sure everything is installed and generated.

Start the example server in a separate terminal by doing "go run example/cmd/excited/main.go".

prototool grpc dirOrProtoFiles... \
--address serverAddress \
--method package.service/Method \
--data 'requestData'

Either use "--data 'requestData'" as the the JSON data to input, or "--stdin" which will result in the input being read from stdin as JSON.

$ make init example # make sure everything is built just in case

$ cat input.json
{"value":"hello"}

$ cat input.json | prototool grpc example \
--address 0.0.0.0:8080 \
--method foo.ExcitedService/Exclamation \
--stdin
{
"value": "hello!"
}

$ cat input.json | prototool grpc example \
--address 0.0.0.0:8080 \
--method foo.ExcitedService/ExclamationServerStream \
--stdin
{
"value": "h"
}
{
"value": "e"
}
{
"value": "l"
}
{
"value": "l"
}
{
"value": "o"
}
{
"value": "!"
}

$ cat input.json
{"value":"hello"}
{"value":"salutations"}

$ cat input.json | prototool grpc example \
--address 0.0.0.0:8080 \
--method foo.ExcitedService/ExclamationClientStream \
--stdin
{
"value": "hellosalutations!"
}

$ cat input.json | prototool grpc example \
--address 0.0.0.0:8080 \
--method foo.ExcitedService/ExclamationBidiStream \
--stdin
{
"value": "hello!"
}
{
"value": "salutations!"
}`,
Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.GRPC(args, flags.headers, flags.address, flags.method, flags.data, flags.callTimeout, flags.connectTimeout, flags.keepaliveTime, flags.stdin)
},
Expand All @@ -180,6 +322,7 @@ var (
initCmdTemplate = &cmdTemplate{
Use: "init [dirPath]",
Short: "Generate an initial config file in the current or given directory.",
Long: `All available options will be generated and commented out except for "protoc_version". Pass the "--uncomment" flag to uncomment all options.`,
Args: cobra.MaximumNArgs(1),
Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.Init(args, flags.uncomment)
Expand All @@ -204,6 +347,7 @@ var (
lintCmdTemplate = &cmdTemplate{
Use: "lint dirOrProtoFiles...",
Short: "Lint proto files and compile with protoc to check for failures.",
Long: `The default rule set follows the Style Guide at https://github.com/uber/prototool/blob/master/etc/style/uber/uber.proto. You can add or exclude lint rules in your "prototool.yaml" file. The default rule set is very strict and is meant to enforce consistent development patterns.`,
Run: func(runner exec.Runner, args []string, flags *flags) error {
return runner.Lint(args, flags.listAllLinters, flags.listLinters)
},
Expand Down Expand Up @@ -294,9 +438,9 @@ type cmdTemplate struct {
func (c *cmdTemplate) Build(exitCodeAddr *int, stdin io.Reader, stdout io.Writer, stderr io.Writer, flags *flags) *cobra.Command {
command := &cobra.Command{}
command.Use = c.Use
command.Short = c.Short
command.Short = strings.TrimSpace(c.Short)
if c.Long != "" {
command.Long = fmt.Sprintf("%s\n%s", c.Short, c.Long)
command.Long = wordwrap.WrapString(fmt.Sprintf("%s\n\n%s", strings.TrimSpace(c.Short), strings.TrimSpace(c.Long)), wordWrapLength)
}
command.Args = c.Args
command.Run = func(_ *cobra.Command, args []string) {
Expand Down