From 90be3caa36e7fb76032f2ca00ee577267803f501 Mon Sep 17 00:00:00 2001 From: lucperkins Date: Mon, 9 Mar 2020 14:56:09 -0700 Subject: [PATCH] Convert notes to admonitions Signed-off-by: lucperkins --- assets/sass/style.sass | 21 +++++++++++- content/docs/example.md | 14 ++++++++ content/docs/guides/auth.md | 7 ++-- content/docs/quickstart/android.md | 6 ++-- content/docs/quickstart/csharp-dotnet.md | 6 ++-- content/docs/quickstart/csharp.md | 33 ++++++++++--------- content/docs/quickstart/dart.md | 4 ++- content/docs/quickstart/php.md | 5 +-- .../docs/tutorials/auth/oauth2-objective-c.md | 4 ++- content/docs/tutorials/basic/cpp.md | 5 ++- content/docs/tutorials/basic/objective-c.md | 5 ++- content/docs/tutorials/basic/python.md | 4 ++- content/docs/tutorials/basic/ruby.md | 4 ++- layouts/partials/admonition.html | 23 +++++++++++++ layouts/shortcodes/danger.html | 1 + layouts/shortcodes/figure.html | 13 ++++++++ layouts/shortcodes/note.html | 1 + layouts/shortcodes/requirement.html | 1 + layouts/shortcodes/success.html | 1 + layouts/shortcodes/warning.html | 1 + 20 files changed, 124 insertions(+), 35 deletions(-) create mode 100644 content/docs/example.md create mode 100644 layouts/partials/admonition.html create mode 100644 layouts/shortcodes/danger.html create mode 100644 layouts/shortcodes/figure.html create mode 100644 layouts/shortcodes/note.html create mode 100644 layouts/shortcodes/requirement.html create mode 100644 layouts/shortcodes/success.html create mode 100644 layouts/shortcodes/warning.html diff --git a/assets/sass/style.sass b/assets/sass/style.sass index 1421a86..91fdbad 100644 --- a/assets/sass/style.sass +++ b/assets/sass/style.sass @@ -229,4 +229,23 @@ $colors: mergeColorMaps(("secondary": ($secondary, $white), "twitter-blue": ($tw margin-bottom: 2rem li + li - margin-top: .5rem \ No newline at end of file + margin-top: .5rem + +=admon($color) + .icon + color: $color + +.admonition + margin-bottom: 2rem + padding: 1.5rem 2rem + border-radius: .5rem + border: 1.5px solid $grey-light + + &.is-warning + +admon($warning) + &.is-success + +admon($success) + &.is-note + +admon($info) + &.is-requirement + +admon($grey) \ No newline at end of file diff --git a/content/docs/example.md b/content/docs/example.md new file mode 100644 index 0000000..a6006ab --- /dev/null +++ b/content/docs/example.md @@ -0,0 +1,14 @@ +--- +title: Example +draft: true +--- + +Example doc! + +{{< success >}} +Ea sunt quis cillum elit ipsum et sint nostrud sit sit ad ullamco minim aliqua. Exercitation excepteur ut tempor elit id. Officia eiusmod fugiat tempor ipsum anim incididunt. Irure incididunt esse do ad in magna eiusmod aliqua excepteur sunt. + +Cupidatat duis est consequat qui tempor elit. Amet aliquip voluptate Lorem ipsum fugiat non amet elit sunt pariatur reprehenderit tempor excepteur nostrud. Consequat tempor ea occaecat quis fugiat officia culpa tempor cillum do. Irure adipisicing enim ipsum consectetur elit. + +Ex Lorem ut consequat est enim aliqua aute incididunt labore aliqua. Consectetur occaecat esse Lorem amet fugiat consectetur commodo ea et aliquip dolore consequat cupidatat ut. Magna nisi labore nostrud proident nulla tempor sit occaecat labore commodo anim voluptate tempor anim. +{{< /success >}} \ No newline at end of file diff --git a/content/docs/guides/auth.md b/content/docs/guides/auth.md index 2430991..da03a8e 100644 --- a/content/docs/guides/auth.md +++ b/content/docs/guides/auth.md @@ -34,10 +34,9 @@ on the channel - Google will not allow connections without SSL/TLS, and most gRPC language implementations will not let you send credentials on an unencrypted channel. -

WARNING: Google credentials should only -be used to connect to Google services. Sending a Google issued OAuth2 token -to a non-Google service could result in this token being stolen and used to -impersonate the client to Google services.

+{{< warning >}} +Google credentials should only be used to connect to Google services. Sending a Google issued OAuth2 token to a non-Google service could result in this token being stolen and used to impersonate the client to Google services. +{{< /warning >}} ### Authentication API diff --git a/content/docs/quickstart/android.md b/content/docs/quickstart/android.md index da3fa38..f39fff3 100644 --- a/content/docs/quickstart/android.md +++ b/content/docs/quickstart/android.md @@ -15,9 +15,9 @@ description: This guide gets you started with gRPC in Android Java with a simple [Android Virtual Device]: https://developer.android.com/studio/run/managing-avds.html [USB debugging]: https://developer.android.com/studio/command-line/adb.html#Enabling -> **Note**: gRPC Java does not support running a server on an Android device. -> For this quick start, the Android client app will connect to a server running -> on your local (non-Android) computer. +{{< note >}} +gRPC Java does not support running a server on an Android device. For this quick start, the Android client app will connect to a server running on your local (non-Android) computer. +{{< /note >}} ### Download the example diff --git a/content/docs/quickstart/csharp-dotnet.md b/content/docs/quickstart/csharp-dotnet.md index 38ff0ce..2d4f9a0 100644 --- a/content/docs/quickstart/csharp-dotnet.md +++ b/content/docs/quickstart/csharp-dotnet.md @@ -5,9 +5,9 @@ short: C# with grpc-dotnet description: This guide gets you started with gRPC for .NET with a simple working example. --- -> **Note**: This is a quick start guide for the "grpc-dotnet" implementation of -> gRPC C#s. See [gRPC C# Quick Start](/docs/quickstart/csharp) for how to start -> with the gRPC C# implementation based on native Core library. +{{< note >}} +This is a quick start guide for the "grpc-dotnet" implementation of gRPC C#s. See [gRPC C# Quick Start](../csharp) for how to start with the gRPC C# implementation based on native Core library. +{{< /note >}} ### General project info diff --git a/content/docs/quickstart/csharp.md b/content/docs/quickstart/csharp.md index 1e6ab45..cb63391 100644 --- a/content/docs/quickstart/csharp.md +++ b/content/docs/quickstart/csharp.md @@ -5,10 +5,9 @@ short: C# description: This guide gets you started with gRPC in C# with a simple working example. --- -> **Note**: This is a quick start guide for the gRPC C# implementation based on -> Core native library. See [gRPC for .NET Quick -> Start](/docs/quickstart/csharp-dotnet/) for how to start with the -> "grpc-dotnet" implementation. +{{< note >}} +This is a quick start guide for the gRPC C# implementation based on Core native library. See [gRPC for .NET Quick Start](..//csharp-dotnet/) for how to start with the "grpc-dotnet" implementation. +{{< /note >}} ### Prerequisites @@ -52,8 +51,10 @@ From the `examples/csharp/Helloworld` directory: > dotnet build Greeter.sln ``` -*NOTE: If you want to use gRPC C# from a project that uses the "classic" .csproj files (supported by Visual Studio 2013, 2015 and older versions of Mono), please refer to the -[Greeter using "classic" .csproj](https://github.com/grpc/grpc/blob/{{< param grpc_release_tag >}}/examples/csharp/HelloworldLegacyCsproj/README.md) example.* +{{< note >}} +If you want to use gRPC C# from a project that uses the "classic" .csproj files (supported by Visual Studio 2013, 2015 and older versions of Mono), please refer to the +[Greeter using "classic" .csproj](https://github.com/grpc/grpc/blob/{{< param grpc_release_tag >}}/examples/csharp/HelloworldLegacyCsproj/README.md) example. +{{< /note >}} ### Run a gRPC application @@ -61,17 +62,17 @@ From the `examples/csharp/Helloworld` directory: * Run the server: -```sh -> cd GreeterServer -> dotnet run -f netcoreapp2.1 -``` + ```sh + > cd GreeterServer + > dotnet run -f netcoreapp2.1 + ``` * From another terminal, run the client: -```sh -> cd GreeterClient -> dotnet run -f netcoreapp2.1 -``` + ```sh + > cd GreeterClient + > dotnet run -f netcoreapp2.1 + ``` Congratulations! You've just run a client-server application with gRPC. @@ -86,7 +87,7 @@ server and the client "stub" have a `SayHello` RPC method that takes a server, and that this method is defined like this: -```C# +```proto // The greeting service definition. service Greeter { // Sends a greeting @@ -108,7 +109,7 @@ Let's update this so that the `Greeter` service has two methods. Edit `examples/protos/helloworld.proto` and update it with a new `SayHelloAgain` method, with the same request and response types: -```C# +```proto // The greeting service definition. service Greeter { // Sends a greeting diff --git a/content/docs/quickstart/dart.md b/content/docs/quickstart/dart.md index 4d1871d..7bc2f6d 100644 --- a/content/docs/quickstart/dart.md +++ b/content/docs/quickstart/dart.md @@ -11,7 +11,9 @@ description: This guide gets you started with gRPC in Dart with a simple working For installation instructions, see [Install Dart](https://dart.dev/install). -> Note: Dart gRPC supports the Flutter and Server platforms. +{{< note >}} +Dart gRPC supports the Flutter and Server platforms. +{{< /note >}} #### Protocol Buffers v3 diff --git a/content/docs/quickstart/php.md b/content/docs/quickstart/php.md index 162c4c8..7fab459 100644 --- a/content/docs/quickstart/php.md +++ b/content/docs/quickstart/php.md @@ -80,8 +80,9 @@ or specific version sudo pecl install grpc-1.7.0 ``` -Note: for users on CentOS/RHEL 6, unfortunately this step won’t work. -Please follow the instructions below to compile the PECL extension from source. +{{< warning >}} +This step unfortunately won’t work on CentOS/RHEL 6. Please follow the instructions below to compile the PECL extension from source. +{{< /warning >}} ##### Install on Windows diff --git a/content/docs/tutorials/auth/oauth2-objective-c.md b/content/docs/tutorials/auth/oauth2-objective-c.md index 44f94f6..77aabe6 100644 --- a/content/docs/tutorials/auth/oauth2-objective-c.md +++ b/content/docs/tutorials/auth/oauth2-objective-c.md @@ -49,13 +49,15 @@ expects Google account credentials, but neither gRPC nor the Objective-C client library is tied to any specific OAuth2 provider). The second view makes a gRPC request to the test server, using the access token obtained by the first view. -Note: OAuth2 libraries need the application to register and obtain an ID from +{{< note >}} +OAuth2 libraries need the application to register and obtain an ID from the identity provider (in the case of this example app, Google). The app's XCode project is configured using that ID, so you shouldn't copy this project "as is" for your own app: it would result in your app being identified in the consent screen as "gRPC-AuthSample", and not having access to real Google services. Instead, configure your own XCode project following the [instructions here](https://developers.google.com/identity/sign-in/ios/). +{{< /note >}} As with the other Objective-C examples, you also should have [Cocoapods](https://cocoapods.org/#install) installed, as well as the relevant diff --git a/content/docs/tutorials/basic/cpp.md b/content/docs/tutorials/basic/cpp.md index 80122d9..c4dffe7 100644 --- a/content/docs/tutorials/basic/cpp.md +++ b/content/docs/tutorials/basic/cpp.md @@ -374,7 +374,10 @@ address and port we want to connect to - in our case we'll use no SSL: ```cpp grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials()); ``` -Note: In order to set additional options for the *channel*, use the `grpc::CreateCustomChannel()` api with any special channel arguments - `grpc::ChannelArguments` + +{{< note >}} +In order to set additional options for the *channel*, use the `grpc::CreateCustomChannel()` api with any special channel arguments - `grpc::ChannelArguments`. +{{< /note >}} Now we can use the channel to create our stub using the `NewStub` method provided in the `RouteGuide` class we generated from our .proto. diff --git a/content/docs/tutorials/basic/objective-c.md b/content/docs/tutorials/basic/objective-c.md index 0bfa621..2e59f58 100644 --- a/content/docs/tutorials/basic/objective-c.md +++ b/content/docs/tutorials/basic/objective-c.md @@ -236,9 +236,12 @@ version, and other metadata. In this section, we'll look at creating an Objective-C client for our `RouteGuide` service. You can see our complete example client code in [examples/objective-c/route_guide/ViewControllers.m](https://github.com/grpc/grpc/blob/{{< param grpc_release_tag >}}/examples/objective-c/route_guide/ViewControllers.m). -(Note: In your apps, for maintainability and readability reasons, you shouldn't + +{{< note >}} +In your apps, for maintainability and readability reasons, you shouldn't put all of your view controllers in a single file; it's done here only to simplify the learning process). +{{< /note >}} #### Constructing a service object diff --git a/content/docs/tutorials/basic/python.md b/content/docs/tutorials/basic/python.md index 50ede2b..7d0471c 100644 --- a/content/docs/tutorials/basic/python.md +++ b/content/docs/tutorials/basic/python.md @@ -173,7 +173,9 @@ than creates a new one. The generated code files are called - `add_RouteGuideServicer_to_server`, which adds a RouteGuideServicer to a `grpc.Server` -Note: The `2` in pb2 indicates that the generated code is following Protocol Buffers Python API version 2. Version 1 is obsolete. It has no relation to the Protocol Buffers Language version, which is the one indicated by `syntax = "proto3"` or `syntax = "proto2"` in a .proto file. +{{< note >}} +The `2` in pb2 indicates that the generated code is following Protocol Buffers Python API version 2. Version 1 is obsolete. It has no relation to the Protocol Buffers Language version, which is the one indicated by `syntax = "proto3"` or `syntax = "proto2"` in a .proto file. +{{< /note >}} ### Creating the server {#server} diff --git a/content/docs/tutorials/basic/ruby.md b/content/docs/tutorials/basic/ruby.md index 66ba94d..c99c21e 100644 --- a/content/docs/tutorials/basic/ruby.md +++ b/content/docs/tutorials/basic/ruby.md @@ -387,7 +387,9 @@ Run the server: $ bundle exec route_guide/route_guide_server.rb ../python/route_guide/route_guide_db.json ``` -> Note: The `route_guide_db.json` file is actually language-agnostic, it happens to be located in the `python` folder. +{{< note >}} +The `route_guide_db.json` file is actually language-agnostic, it happens to be located in the `python` folder. +{{< /note >}} From a different terminal, run the client: diff --git a/layouts/partials/admonition.html b/layouts/partials/admonition.html new file mode 100644 index 0000000..f3aa78c --- /dev/null +++ b/layouts/partials/admonition.html @@ -0,0 +1,23 @@ +{{ $content := .content | markdownify }} +{{ $name := .type | humanize }} +
+
+
+
+ + + +
+ +
+

+ {{ $name }} +

+ +
+ {{ $content }} +
+
+
+
+
diff --git a/layouts/shortcodes/danger.html b/layouts/shortcodes/danger.html new file mode 100644 index 0000000..6230f2e --- /dev/null +++ b/layouts/shortcodes/danger.html @@ -0,0 +1 @@ +{{ partial "admonition.html" (dict "type" "warning" "icon" "exclamation-triangle" "content" .Inner) }} diff --git a/layouts/shortcodes/figure.html b/layouts/shortcodes/figure.html new file mode 100644 index 0000000..92125b6 --- /dev/null +++ b/layouts/shortcodes/figure.html @@ -0,0 +1,13 @@ +{{ $src := .Get "src" | relURL }} +{{ $caption := .Get "caption" }} +
+ + + + + {{ with $caption }} +
+ {{ . | markdownify }} +
+ {{ end }} +
diff --git a/layouts/shortcodes/note.html b/layouts/shortcodes/note.html new file mode 100644 index 0000000..3398473 --- /dev/null +++ b/layouts/shortcodes/note.html @@ -0,0 +1 @@ +{{ partial "admonition.html" (dict "type" "note" "icon" "info-circle" "content" .Inner "title" (.Get "title")) }} diff --git a/layouts/shortcodes/requirement.html b/layouts/shortcodes/requirement.html new file mode 100644 index 0000000..158fb21 --- /dev/null +++ b/layouts/shortcodes/requirement.html @@ -0,0 +1 @@ +{{ partial "admonition.html" (dict "type" "requirement" "icon" "wrench" "content" .Inner "title" (.Get "title")) }} diff --git a/layouts/shortcodes/success.html b/layouts/shortcodes/success.html new file mode 100644 index 0000000..070935d --- /dev/null +++ b/layouts/shortcodes/success.html @@ -0,0 +1 @@ +{{ partial "admonition.html" (dict "type" "success" "icon" "check-circle" "content" .Inner "title" (.Get "title")) }} diff --git a/layouts/shortcodes/warning.html b/layouts/shortcodes/warning.html new file mode 100644 index 0000000..6230f2e --- /dev/null +++ b/layouts/shortcodes/warning.html @@ -0,0 +1 @@ +{{ partial "admonition.html" (dict "type" "warning" "icon" "exclamation-triangle" "content" .Inner) }}