=doc Migrate docs from Sphinx to Paradox

Converts .rst files to .md in a best effor way using:

 - https://github.com/jonas/akkadocs-sphinx2paradox

Fixes akka#1

docs/src/main/paradox/index.md

@@ -0,0 +1,10 @@
+# Contents
+
+@@toc{ depth=1 }
+
+@@@ index
+
+* [java](java.md)
+* [scala](scala.md)
+
+@@@

docs/src/main/paradox/java.md

@@ -0,0 +1,10 @@
+<a id="java-api"></a>
+# Java Documentation
+
+@@toc{ depth=2 }
+
+@@@ index
+
+* [java/http/index](java/http/index.md)
+
+@@@

docs/src/main/paradox/java/http/client-side/client-https-support.md

@@ -0,0 +1,108 @@
+<a id="clientsidehttps-java"></a>
+# Client-Side HTTPS Support
+
+Akka HTTP supports TLS encryption on the client-side as well as on the @ref[server-side](../server-side-https-support.md#serversidehttps-java).
+
+> **Warning:**
+Akka HTTP 1.0 does not completely validate certificates when using HTTPS. Please do not treat HTTPS connections
+made with this version as secure. Requests are vulnerable to a Man-In-The-Middle attack via certificate substitution.
+
+The central vehicle for configuring encryption is the `HttpsConnectionContext`, which can be created using
+the static method `ConnectionContext.https` which is defined like this:
+
+@@snip [ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala) { #https-context-creation }
+
+In addition to the `outgoingConnection`, `newHostConnectionPool` and `cachedHostConnectionPool` methods the
+[akka.http.javadsl.Http](@github@/akka-http-core/src/main/scala/akka/http/javadsl/Http.scala) extension also defines `outgoingConnectionTls`, `newHostConnectionPoolTls` and
+`cachedHostConnectionPoolTls`. These methods work identically to their counterparts without the `-Tls` suffix,
+with the exception that all connections will always be encrypted.
+
+The `singleRequest` and `superPool` methods determine the encryption state via the scheme of the incoming request,
+i.e. requests to an "https" URI will be encrypted, while requests to an "http" URI won't.
+
+The encryption configuration for all HTTPS connections, i.e. the `HttpsContext` is determined according to the
+following logic:
+
+ 1. If the optional `httpsContext` method parameter is defined it contains the configuration to be used (and thus
+takes precedence over any potentially set default client-side `HttpsContext`).
+ 2. If the optional `httpsContext` method parameter is undefined (which is the default) the default client-side
+`HttpsContext` is used, which can be set via the `setDefaultClientHttpsContext` on the `Http` extension.
+ 3. If no default client-side `HttpsContext` has been set via the `setDefaultClientHttpsContext` on the `Http`
+extension the default system configuration is used.
+
+Usually the process is, if the default system TLS configuration is not good enough for your application's needs,
+that you configure a custom `HttpsContext` instance and set it via `Http.get(system).setDefaultClientHttpsContext`.
+Afterwards you simply use `outgoingConnectionTls`, `newHostConnectionPoolTls`, `cachedHostConnectionPoolTls`,
+`superPool` or `singleRequest` without a specific `httpsContext` argument, which causes encrypted connections
+to rely on the configured default client-side `HttpsContext`.
+
+If no custom `HttpsContext` is defined the default context uses Java's default TLS settings. Customizing the
+`HttpsContext` can make the Https client less secure. Understand what you are doing!
+
+## SSL-Config
+
+Akka HTTP heavily relies on, and delegates most configuration of any SSL/TLS related options to
+[Lightbend SSL-Config](http://typesafehub.github.io/ssl-config/), which is a library specialized in providing an secure-by-default SSLContext
+and related options.
+
+Please refer to the [Lightbend SSL-Config](http://typesafehub.github.io/ssl-config/) documentation for detailed documentation of all available settings.
+
+SSL Config settings used by Akka HTTP (as well as Streaming TCP) are located under the *akka.ssl-config* namespace.
+
+## Detailed configuration and workarounds
+
+Akka HTTP relies on [Typesafe SSL-Config](http://typesafehub.github.io/ssl-config) which is a library maintained by Lightbend that makes configuring
+things related to SSL/TLS much simpler than using the raw SSL APIs provided by the JDK. Please refer to its
+documentation to learn more about it.
+
+All configuration options available to this library may be set under the `akka.ssl-context` configuration for Akka HTTP applications.
+
+> **Note:**
+When encountering problems connecting to HTTPS hosts we highly encourage to reading up on the excellent ssl-config
+configuration. Especially the quick start sections about [adding certificates to the trust store](http://typesafehub.github.io/ssl-config/WSQuickStart.html#connecting-to-a-remote-server-over-https) should prove
+very useful, for example to easily trust a self-signed certificate that applications might use in development mode.
+
+> **Warning:**
+While it is possible to disable certain checks using the so called "loose" settings in SSL Config, we **strongly recommend**
+to instead attempt to solve these issues by properly configuring TLS–for example by adding trusted keys to the keystore.
+If however certain checks really need to be disabled because of misconfigured (or legacy) servers that your
+application has to speak to, instead of disabling the checks globally (i.e. in `application.conf`) we suggest
+configuring the loose settings for *specific connections* that are known to need them disabled (and trusted for some other reason).
+The pattern of doing so is documented in the folowing sub-sections.
+
+### Hostname verification
+
+Hostname verification proves that the Akka HTTP client is actually communicating with the server it intended to
+communicate with. Without this check a man-in-the-middle attack is possible. In the attack scenario, an alternative
+certificate would be presented which was issued for another host name. Checking the host name in the certificate
+against the host name the connection was opened against is therefore vital.
+
+The default `HttpsContext` enables hostname verification. Akka HTTP relies on the [Typesafe SSL-Config](http://typesafehub.github.io/ssl-config) library
+to implement this and security options for SSL/TLS. Hostname verification is provided by the JDK
+and used by Akka HTTP since Java 7, and on Java 6 the verification is implemented by ssl-config manually.
+
+For further recommended reading we would like to highlight the [fixing hostname verification blog post](https://tersesystems.com/2014/03/23/fixing-hostname-verification/) by blog post by Will Sargent.
+
+### Server Name Indication (SNI)
+
+SNI is an TLS extension which aims to guard against man-in-the-middle attacks. It does so by having the client send the
+name of the virtual domain it is expecting to talk to as part of the TLS handshake.
+
+It is specified as part of [RFC 6066](https://tools.ietf.org/html/rfc6066#page-6).
+
+### Disabling TLS security features, at your own risk
+
+> **Warning:**
+It is highly discouraged to disable any of the security features of TLS, however do acknowlage that workarounds may sometimes be needed.
+Before disabling any of the features one should consider if they may be solvable *within* the TLS world,
+for example by [trusting a certificate](http://typesafehub.github.io/ssl-config/WSQuickStart.html), or [configuring the trusted cipher suites](http://typesafehub.github.io/ssl-config/CipherSuites.html).
+There's also a very important section in the ssl-config docs titled [LooseSSL - Please read this before turning anything off!](http://typesafehub.github.io/ssl-config/LooseSSL.html#please-read-this-before-turning-anything-off).
+If disabling features is indeed desired, we recommend doing so for *specific connections*,
+instead of globally configuring it via `application.conf`.
+
+The following shows an example of disabling SNI for a given connection:
+
+@@snip [HttpsExamplesDocTest.java](../../../../java/docs/http/javadsl/HttpsExamplesDocTest.java) { #disable-sni-connection }
+
+The `badSslConfig` is a copy of the default `AkkaSSLConfig` with with the slightly changed configuration to disable SNI.
+This value can be cached and used for connections which should indeed not use this feature.

docs/src/main/paradox/java/http/client-side/connection-level.md

@@ -0,0 +1,68 @@
+<a id="connection-level-api-java"></a>
+# Connection-Level Client-Side API
+
+The connection-level API is the lowest-level client-side API Akka HTTP provides. It gives you full control over when
+HTTP connections are opened and closed and how requests are to be send across which connection. As such it offers the
+highest flexibility at the cost of providing the least convenience.
+
+## Opening HTTP Connections
+
+With the connection-level API you open a new HTTP connection to a target endpoint by materializing a `Flow`
+returned by the `Http.get(system).outgoingConnection(...)` method. Here is an example:
+
+@@snip [HttpClientExampleDocTest.java](../../../../java/docs/http/javadsl/HttpClientExampleDocTest.java) { #outgoing-connection-example }
+
+Apart from the host name and port the `Http.get(system).outgoingConnection(...)` method also allows you to specify socket options
+and a number of configuration settings for the connection.
+
+Note that no connection is attempted until the returned flow is actually materialized! If the flow is materialized
+several times then several independent connections will be opened (one per materialization).
+If the connection attempt fails, for whatever reason, the materialized flow will be immediately terminated with a
+respective exception.
+
+## Request-Response Cycle
+
+Once the connection flow has been materialized it is ready to consume `HttpRequest` instances from the source it is
+attached to. Each request is sent across the connection and incoming responses dispatched to the downstream pipeline.
+Of course and as always, back-pressure is adequately maintained across all parts of the
+connection. This means that, if the downstream pipeline consuming the HTTP responses is slow, the request source will
+eventually be slowed down in sending requests.
+
+Any errors occurring on the underlying connection are surfaced as exceptions terminating the response stream (and
+canceling the request source).
+
+Note that, if the source produces subsequent requests before the prior responses have arrived, these requests will be
+[pipelined](http://en.wikipedia.org/wiki/HTTP_pipelining) across the connection, which is something that is not supported by all HTTP servers.
+Also, if the server closes the connection before responses to all requests have been received this will result in the
+response stream being terminated with a truncation error.
+
+## Closing Connections
+
+Akka HTTP actively closes an established connection upon reception of a response containing `Connection: close` header.
+The connection can also be closed by the server.
+
+An application can actively trigger the closing of the connection by completing the request stream. In this case the
+underlying TCP connection will be closed when the last pending response has been received.
+
+The connection will also be closed if the response entity is cancelled (e.g. by attaching it to `Sink.cancelled()`)
+or consumed only partially (e.g. by using `take` combinator). In order to prevent this behaviour the entity should be
+explicitly drained by attaching it to `Sink.ignore()`.
+
+## Timeouts
+
+Timeouts are configured in the same way for Scala and Akka. See @ref[Akka HTTP Timeouts](../common/timeouts.md#http-timeouts-java) .
+
+<a id="http-client-layer-java"></a>
+## Stand-Alone HTTP Layer Usage
+
+Due to its Reactive-Streams-based nature the Akka HTTP layer is fully detachable from the underlying TCP
+interface. While in most applications this "feature" will not be crucial it can be useful in certain cases to be able
+to "run" the HTTP layer (and, potentially, higher-layers) against data that do not come from the network but rather
+some other source. Potential scenarios where this might be useful include tests, debugging or low-level event-sourcing
+(e.g by replaying network traffic).
+
+On the client-side the stand-alone HTTP layer forms a `BidiFlow<HttpRequest, SslTlsOutbound, SslTlsInbound, HttpResponse, NotUsed>`,
+that is a stage that "upgrades" a potentially encrypted raw connection to the HTTP level.
+
+You create an instance of the layer by calling one of the two overloads of the `Http.get(system).clientLayer` method,
+which also allows for varying degrees of configuration.