[Docs] Split into different sections #190

eperinan · 2018-03-07T00:49:14Z

This PR splits the current documentation into different sections and solves #176

This PR is related to frees-io/freestyle#534 where I am creating the entries for the menu. If we do some changes related to the paths, for example, we will have to do on both sides.

This PR resolves #179, #178 and #177

Split into different sections
Adds Compression Support
Adds SSL/TLS Encryption Support (Netty)
Adds fs2 Streaming docs
Check and reword pattern section
Review al compilation tut errors after split into different sections

juanpedromoreno · 2018-03-07T09:33:22Z

docs/src/main/tut/implementations.md

+permalink: /docs/rpc/implementations
+---
+
+# RPC Service Implementations


I'd re-define this sections towards to be the Patterns one.

L-Lavigne · 2018-03-08T18:30:15Z

docs/src/main/tut/quickstart.md

+--- | --- | --- | ---
+`frees-rpc-server` | Server | Yes | Needed to attach RPC Services and spin-up an RPC Server.
+`frees-rpc-client-core` | Client | Yes | Mandatory to define protocols and auto-derived clients.
+`frees-rpc-client-netty` | Client | Yes* | Optional if you use `OkHttp`, required from the client perspective.


Not about the document split as such, but is this line accurate? I could see it meaning "netty is optional because if you use okhttp then you don't need to depend on netty" but it seems a bit confusing. I suggest changing it to just "Mandatory on the client side if using Netty". Same goes for the following line.

Makes sense to me. Changed description to "Mandatory on the client side if we are using Netty in the server side"

L-Lavigne · 2018-03-12T17:40:15Z

docs/src/main/tut/quickstart.md

@@ -25,7 +25,7 @@ It's divided into multiple and different artifacts, grouped by scope:
 --- | --- | --- | ---
 `frees-rpc-server` | Server | Yes | Needed to attach RPC Services and spin-up an RPC Server.
 `frees-rpc-client-core` | Client | Yes | Mandatory to define protocols and auto-derived clients.
-`frees-rpc-client-netty` | Client | Yes* | Optional if you use `OkHttp`, required from the client perspective.
+`frees-rpc-client-netty` | Client | Yes* | Mandatory on the client side if we are using Netty in the server side.


Thanks for updating - could you confirm if it's mandatory for the client implementation to match the server's though?

Also we'll want to adjust the following line in a similar way, for OkHttp. Thanks!

Yes, the matching it's mandatory.

L-Lavigne · 2018-03-12T23:34:15Z

LGTM 👍

L-Lavigne

Various grammar fixes

L-Lavigne · 2018-03-13T18:31:58Z

docs/src/main/tut/core-concepts.md

@@ -191,22 +191,20 @@ We'll see more details about these and other annotations in the following sectio

 ## Compression

-[frees-rpc] allows you to compress the datas in our services. We can enable this compression in the server or in the client side.
+[frees-rpc] allows you to compress the data whose we are sending in our services. We can enable this compression either on the server or client side.


Grammar fix:
[frees-rpc] allows us to compress the data we are sending in our services. We can enable this compression either on the server or the client side.

L-Lavigne · 2018-03-13T18:41:31Z

docs/src/main/tut/core-concepts.md


-[frees-rpc] supports `Gzip` as compression format.
+[frees-rpc] supports only `Gzip` as compression format so far and the usage it's really easy. 


The original line is fine here IMO

L-Lavigne · 2018-03-13T18:46:33Z

docs/src/main/tut/ssl-tls.md

+> [gRPC](https://grpc.io/docs/guides/auth.html) has SSL/TLS integration and promotes the use of SSL/TLS to authenticate the server, and encrypt all the data exchanged between the client and the server. Optional mechanisms are available for clients to provide certificates for mutual authentication.
+
+[frees-rpc] allows you to encrypt the connection between the server and the client through SSL/TLS. The main goal of use SSL is protect your sensitive information and keeps your data secure between servers and clients.


Grammar fix: replace of use SSL is protect to of using SSL is to protect

L-Lavigne · 2018-03-13T18:51:28Z

docs/src/main/tut/ssl-tls.md

+[frees-rpc] allows you to encrypt the connection between the server and the client through SSL/TLS. The main goal of use SSL is protect your sensitive information and keeps your data secure between servers and clients.
+
+As we mentioned in the [Quickstart](/docs/rpc/quickstart) section, we can choose and configure our client with `okhttp` or `netty` but if we want to encrypt our service, it's mandatory to use `Netty`.


We should have consistent capitalization in the transport names here and below

L-Lavigne · 2018-03-13T18:52:17Z

docs/src/main/tut/ssl-tls.md

+On the server and client side, we will need two files to configure the `SslContext` in `gRPC`:
+
+* Server certificate file: Small data files that digitally bind a cryptographic key to an organization’s details. This file could be generated or get from a third company.


Grammar fix: change get to obtained.

L-Lavigne · 2018-03-14T16:38:15Z

docs/src/main/tut/ssl-tls.md

+
+## Usage
+
+The first step to do, in order to start to secure ours `freestyle-rpc` services, is use the artifacts `frees-rpc-netty-ssl` and `frees-rpc-client-netty` in our `build.sbt`.


The first step to securing our freestyle-rpc services is to add the library dependencies frees-rpc-netty-ssl and frees-rpc-client-netty in our build.sbt.

L-Lavigne · 2018-03-14T16:56:28Z

docs/src/main/tut/ssl-tls.md

+
+In second place, we will have to move to our `resources` folder both server/client certificates and private keys. 
+
+In our tests, the certificates have been extracted from [here](https://github.com/grpc/grpc-java/tree/master/testing/src/main/resources/certs). It could be a good point to start to check that our application works meanwhile we generate or obtain our own certificates.


If we haven't yet generated or obtained our own certificates, we can test using certificates found here.

L-Lavigne · 2018-03-14T17:08:23Z

docs/src/main/tut/ssl-tls.md

+
+Thirdly, let's see a piece of code where we will explain line by line, what we are doing on the server side.
+
+We are going to ignore the explanations related to create the `RPCService`, `ServerRPCService` and runtime implicits. If you have any doubt about it, please, take a look at the [Patterns](/docs/rpc/patterns) section.


We won't cover the details regarding creation of RPCService, ServerRPCService and runtime implicits. You can find more information about these in the Patterns section.

L-Lavigne · 2018-03-14T17:10:34Z

docs/src/main/tut/ssl-tls.md

+
+	// Important, the channel interpreter have to be NettyChannelInterpreter.
+
+	// In this case, we are creating the channel interpreter with a specifics ManagedChannelConfig


// In this case, we are creating the channel interpreter with a specific ManagedChannelConfig

L-Lavigne · 2018-03-14T17:11:00Z

docs/src/main/tut/ssl-tls.md

+	// Important, the channel interpreter have to be NettyChannelInterpreter.
+
+	// In this case, we are creating the channel interpreter with a specifics ManagedChannelConfig
+	// These configs allow us encrypted the connection with the server.


// These configs allow us to encrypt the connection with the server.

L-Lavigne · 2018-03-16T16:10:23Z

LGTM, good work 👍

Note that we'll need to merge the docs changes from this and #195 once either of them is in master.

* Adds some changes to the core-concepts and streaming docs * More fixes * Adds suggestions * More minor changes * Fixes typos

juanpedromoreno

Outstanding job @eperinan ! LGTM

Adds new content with their titles and paths

c3a91fb

eperinan added the WIP label Mar 7, 2018

eperinan self-assigned this Mar 7, 2018

eperinan added the in progress label Mar 7, 2018

eperinan added 2 commits March 7, 2018 01:51

Moves references to his file

52976b8

First approach of splitting docs into separates files

66d263b

juanpedromoreno reviewed Mar 7, 2018

View reviewed changes

juanpedromoreno mentioned this pull request Mar 8, 2018

[Docs] Add new Microservices item with nested_options frees-io/freestyle#534

Merged

L-Lavigne reviewed Mar 8, 2018

View reviewed changes

eperinan added 2 commits March 12, 2018 01:40

WIP: Adding index layout, moving sections and new docs

35ebd55

Addresses comments of Lavigne

5dc7650

L-Lavigne reviewed Mar 12, 2018

View reviewed changes

Fix description in artifact frees-rpc-client-okhttp

db79b9c

eperinan added 2 commits March 13, 2018 00:53

End up docs related to Compression Support

13864c1

Wip: Docs - SSL/TLS Encryption Support (Netty)

19b9916

L-Lavigne reviewed Mar 13, 2018

View reviewed changes

eperinan added 2 commits March 14, 2018 00:11

Solved grammar fixes

3f1dc6b

End up SSL/TLS Netty section

272d371

eperinan force-pushed the ep-new-docs branch from 0cfa997 to 272d371 Compare March 14, 2018 00:36

eperinan added 2 commits March 14, 2018 16:43

Ends up streaming documentation

8e493e4

Small review to all our documents except tut files

50c4151

L-Lavigne reviewed Mar 14, 2018

View reviewed changes

eperinan added 2 commits March 15, 2018 00:17

Reviews grammar in ssl/tls section

be23a4a

Fixed erros tut compilation

00f48e6

juanpedromoreno added 2 commits March 16, 2018 18:24

Fixes links references in every document (#196)

78b66d8

Adds some changes to the core-concepts and streaming docs (#197)

3a1d142

* Adds some changes to the core-concepts and streaming docs * More fixes * Adds suggestions * More minor changes * Fixes typos

juanpedromoreno approved these changes Mar 16, 2018

View reviewed changes

juanpedromoreno merged commit fe6c6de into master Mar 16, 2018

juanpedromoreno deleted the ep-new-docs branch March 16, 2018 20:03

juanpedromoreno removed the in progress label Mar 16, 2018

juanpedromoreno mentioned this pull request Mar 18, 2018

Releases frees-rpc 0.12.0 #198

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Split into different sections #190

[Docs] Split into different sections #190

eperinan commented Mar 7, 2018 •

edited

juanpedromoreno Mar 7, 2018

L-Lavigne Mar 8, 2018

eperinan Mar 12, 2018

L-Lavigne Mar 12, 2018

juanpedromoreno Mar 12, 2018

L-Lavigne commented Mar 12, 2018

L-Lavigne left a comment

L-Lavigne Mar 13, 2018

L-Lavigne Mar 13, 2018

L-Lavigne Mar 13, 2018 •

edited

L-Lavigne Mar 13, 2018

L-Lavigne Mar 13, 2018

L-Lavigne Mar 14, 2018

L-Lavigne Mar 14, 2018

L-Lavigne Mar 14, 2018

L-Lavigne Mar 14, 2018

L-Lavigne Mar 14, 2018

L-Lavigne commented Mar 16, 2018

juanpedromoreno left a comment


		[frees-rpc] supports `Gzip` as compression format.
		[frees-rpc] supports only `Gzip` as compression format so far and the usage it's really easy.

		> [gRPC](https://grpc.io/docs/guides/auth.html) has SSL/TLS integration and promotes the use of SSL/TLS to authenticate the server, and encrypt all the data exchanged between the client and the server. Optional mechanisms are available for clients to provide certificates for mutual authentication.

		[frees-rpc] allows you to encrypt the connection between the server and the client through SSL/TLS. The main goal of use SSL is protect your sensitive information and keeps your data secure between servers and clients.

		[frees-rpc] allows you to encrypt the connection between the server and the client through SSL/TLS. The main goal of use SSL is protect your sensitive information and keeps your data secure between servers and clients.

		As we mentioned in the [Quickstart](/docs/rpc/quickstart) section, we can choose and configure our client with `okhttp` or `netty` but if we want to encrypt our service, it's mandatory to use `Netty`.

		On the server and client side, we will need two files to configure the `SslContext` in `gRPC`:

		* Server certificate file: Small data files that digitally bind a cryptographic key to an organization’s details. This file could be generated or get from a third company.


		## Usage

		The first step to do, in order to start to secure ours `freestyle-rpc` services, is use the artifacts `frees-rpc-netty-ssl` and `frees-rpc-client-netty` in our `build.sbt`.


		In second place, we will have to move to our `resources` folder both server/client certificates and private keys.

		In our tests, the certificates have been extracted from [here](https://github.com/grpc/grpc-java/tree/master/testing/src/main/resources/certs). It could be a good point to start to check that our application works meanwhile we generate or obtain our own certificates.


		Thirdly, let's see a piece of code where we will explain line by line, what we are doing on the server side.

		We are going to ignore the explanations related to create the `RPCService`, `ServerRPCService` and runtime implicits. If you have any doubt about it, please, take a look at the [Patterns](/docs/rpc/patterns) section.


		// Important, the channel interpreter have to be NettyChannelInterpreter.

		// In this case, we are creating the channel interpreter with a specifics ManagedChannelConfig

[Docs] Split into different sections #190

[Docs] Split into different sections #190

Conversation

eperinan commented Mar 7, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

L-Lavigne commented Mar 12, 2018

L-Lavigne left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

L-Lavigne Mar 13, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

L-Lavigne commented Mar 16, 2018

juanpedromoreno left a comment

Choose a reason for hiding this comment

eperinan commented Mar 7, 2018 •

edited

L-Lavigne Mar 13, 2018 •

edited