Include examples list

README.md

@@ -16,26 +16,29 @@ requests and how to handle responses. Requests are sent using one of the backend
 
 Backend implementations include the HTTP client that is shipped with Java, as well as ones based on [akka-http](https://doc.akka.io/docs/akka-http/current/scala/http/), [http4s](https://http4s.org), [OkHttp](http://square.github.io/okhttp/). They integrate with [Akka](https://akka.io), [Monix](https://monix.io), [fs2](https://github.com/functional-streams-for-scala/fs2), [cats-effect](https://github.com/typelevel/cats-effect), [scalaz](https://github.com/scalaz/scalaz) and [ZIO](https://github.com/zio/zio). Supported Scala versions include 2.12, 2.13 and 3, Scala.JS and Scala Native; supported Java versions include 11+.
 
-Here's a quick example of sttp client in action:
+Here's a quick example of sttp client in action, runnable using [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-import sttp.client4._
+//> using dep com.softwaremill.sttp.client4::core:4.0.0-M20
+
+import sttp.client4.*
+
+@main def sttpDemo(): Unit =
+  val sort: Option[String] = None
+  val query = "http language:scala"
 
-val sort: Option[String] = None
-val query = "http language:scala"
+  // the `query` parameter is automatically url-encoded
+  // `sort` is removed, as the value is not defined
+  val request = basicRequest.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
 
-// the `query` parameter is automatically url-encoded
-// `sort` is removed, as the value is not defined
-val request = basicRequest.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
-
-val backend = DefaultSyncBackend()
-val response = request.send(backend)
+  val backend = DefaultSyncBackend()
+  val response = request.send(backend)
 
-// response.header(...): Option[String]
-println(response.header("Content-Length")) 
+  // response.header(...): Option[String]
+  println(response.header("Content-Length")) 
 
-// response.body: by default read into an Either[String, String] to indicate failure or success 
-println(response.body)                                 
+  // response.body: by default read into an Either[String, String] to indicate failure or success 
+  println(response.body)
 ```
 
 ## Documentation

docs/_static/css/custom.css

@@ -23,7 +23,7 @@
     border-color: rgb(249 219 175);
 }
 
-.example-server {
+.example-backend {
     color: rgb(6 118 71);
     background-color: rgb(236 253 243);
     border-color: rgb(169 239 197);
@@ -39,4 +39,4 @@
     color: rgb(6 89 134);
     background-color: rgb(240 249 255);
     border-color: rgb(185 230 254);
-}
+}

docs/index.md

@@ -9,28 +9,29 @@ requests and how to handle responses. Requests are sent using one of the backend
 
 Backend implementations include the HTTP client that is shipped with Java, as well as ones based on [akka-http](https://doc.akka.io/docs/akka-http/current/scala/http/), [pekko-http](https://pekko.apache.org/docs/pekko-http/current/), [http4s](https://http4s.org), [OkHttp](http://square.github.io/okhttp/). They integrate with [Akka](https://akka.io), [Monix](https://monix.io), [fs2](https://github.com/functional-streams-for-scala/fs2), [cats-effect](https://github.com/typelevel/cats-effect), [scalaz](https://github.com/scalaz/scalaz) and [ZIO](https://github.com/zio/zio). Supported Scala versions include 2.12, 2.13 and 3, Scala.JS and Scala Native; supported Java versions include 11+.
 
-Here's a quick example of sttp client in action:
+Here's a quick example of sttp client in action, runnable using [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala mdoc:compile-only
+//> using dep com.softwaremill.sttp.client4::core:4.0.0-M20
+
 import sttp.client4.*
 
-val query = "http language:scala"
-val sort: Option[String] = None
+@main def sttpDemo(): Unit =
+  val sort: Option[String] = None
+  val query = "http language:scala"
 
-// the `query` parameter is automatically url-encoded
-// `sort` is removed, as the value is not defined
-val request = basicRequest.get(
-  uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
+  // the `query` parameter is automatically url-encoded
+  // `sort` is removed, as the value is not defined
+  val request = basicRequest.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
 
-val backend = DefaultSyncBackend()
-val response = request.send(backend)
+  val backend = DefaultSyncBackend()
+  val response = request.send(backend)
 
-// response.header(...): Option[String]
-println(response.header("Content-Length"))
+  // response.header(...): Option[String]
+  println(response.header("Content-Length")) 
 
-// response.body: by default read into an Either[String, String] 
-// to indicate failure or success 
-println(response.body)     
+  // response.body: by default read into an Either[String, String] to indicate failure or success 
+  println(response.body)
 ```
 
 For more examples, see the [usage examples](examples.md) section. To start using sttp client in your project, see the [quickstart](quickstart.md). Or, browse the documentation to find the topics that interest you the most! ScalaDoc is available at [https://www.javadoc.io](https://www.javadoc.io/doc/com.softwaremill.sttp.client4/core_2.12/4.0.0-M9).

docs/requests/authentication.md

@@ -19,7 +19,7 @@ val token = "zMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F"
 basicRequest.auth.bearer(token)
 ```
 
-### Important Note on the `Authorization` Header and Redirects
+## Important Note on the `Authorization` Header and Redirects
 
 The `Authorization` header is by default removed during redirects. See [redirects](../conf/redirects.md) for more details.
 

examples-ce2/src/main/scala/sttp/client4/examples/PostSerializeJsonMonixHttpClientCirce.scala

@@ -1,4 +1,4 @@
-// {cat=Hello, World!; effects=Monix; backend=HttpClient}: POST JSON data
+// {cat=Hello, World!; effects=Monix; backend=HttpClient}: Post JSON data
 
 //> using scala 2.13
 //> using dep com.softwaremill.sttp.client4::monix:4.0.0-M20

examples/src/main/scala/sttp/client4/examples/GetRawResponseBodySynchronous.scala

@@ -1,4 +1,4 @@
-// {cat=Hello, World!; effects=Direct; backend=HttpClient}: Handle the body by both parsing it to JSON and returning the raw string
+// {cat=Other; effects=Direct; backend=HttpClient}: Handle the body by both parsing it to JSON and returning the raw string
 
 //> using dep com.softwaremill.sttp.client4::circe:4.0.0-M20
 //> using dep io.circe::circe-generic:0.14.10

examples/src/main/scala/sttp/client4/examples/WebSocketSynchronous.scala

@@ -1,4 +1,4 @@
-// {cat=WebSocket; effects=Dir4ect; backend=HttpClient}: Connect to & interact with a WebSocket
+// {cat=WebSocket; effects=Direct; backend=HttpClient}: Connect to & interact with a WebSocket
 
 //> using dep com.softwaremill.sttp.client4::core:4.0.0-M20
 

examples/src/main/scala/sttp/client4/examples/x.scala

@@ -0,0 +1,20 @@
+//> using dep com.softwaremill.sttp.client4::core:4.0.0-M20
+
+import sttp.client4.*
+
+@main def sttpDemo(): Unit =
+  val sort: Option[String] = None
+  val query = "http language:scala"
+
+  // the `query` parameter is automatically url-encoded
+  // `sort` is removed, as the value is not defined
+  val request = basicRequest.get(uri"https://api.github.com/search/repositories?q=$query&sort=$sort")
+
+  val backend = DefaultSyncBackend()
+  val response = request.send(backend)
+
+  // response.header(...): Option[String]
+  println(response.header("Content-Length")) 
+
+  // response.body: by default read into an Either[String, String] to indicate failure or success 
+  println(response.body)

generated-docs/out/.python-version

@@ -1 +1 @@
-3.7.2
+3.12

generated-docs/out/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = sttp
+SPHINXPROJ    = tapir
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

generated-docs/out/_static/css/custom.css

@@ -23,7 +23,7 @@
     border-color: rgb(249 219 175);
 }
 
-.example-server {
+.example-backend {
     color: rgb(6 118 71);
     background-color: rgb(236 253 243);
     border-color: rgb(169 239 197);
@@ -39,4 +39,4 @@
     color: rgb(6 89 134);
     background-color: rgb(240 249 255);
     border-color: rgb(185 230 254);
-}
+}

generated-docs/out/backends/akka.md

@@ -66,7 +66,7 @@ val response: Future[Response[Either[String, Source[ByteString, Any]]]] =
   basicRequest
     .post(uri"...")
     .response(asStreamUnsafe(AkkaStreams))
-    .send(backend)
+    .send(backend)           
 ```
 
 The akka-http backend support both regular and streaming [websockets](../websockets.md).
@@ -101,7 +101,7 @@ Non-standard behavior:
 
 Received data streams can be parsed to a stream of server-sent events (SSE):
 
-```scala
+```scala 
 import scala.concurrent.Future
 
 import akka.stream.scaladsl.Source

generated-docs/out/backends/catseffect.md

@@ -126,7 +126,7 @@ val client = WebClient.builder("https://my-service.com")
 val backend = ArmeriaCatsBackend.usingClient[IO](client)
 ```
 
-```eval_rst
+```{eval-rst}
 .. note:: A WebClient could fail to follow redirects if the WebClient is created with a base URI and a redirect location is a different URI.
 ```
 

generated-docs/out/backends/fs2.md

@@ -72,7 +72,6 @@ Host header override is supported in environments running Java 12 onwards, but i
 -Djdk.httpclient.allowRestrictedHeaders=host
 ```
 
-
 ## Using Armeria
 
 To use, add the following dependency to your project:
@@ -103,7 +102,7 @@ or, if you'd like to instantiate the [WebClient](https://armeria.dev/docs/client
 import cats.effect.IO
 import cats.effect.std.Dispatcher
 import com.linecorp.armeria.client.WebClient
-import com.linecorp.armeria.client.circuitbreaker._
+import com.linecorp.armeria.client.circuitbreaker.*
 import sttp.client4.armeria.fs2.ArmeriaFs2Backend
 
 val dispatcher: Dispatcher[IO] = ???
@@ -118,7 +117,7 @@ val client = WebClient.builder("https://my-service.com")
 val backend = ArmeriaFs2Backend.usingClient[IO](client, dispatcher)
 ```
 
-```eval_rst
+```{eval-rst}
 .. note:: A WebClient could fail to follow redirects if the WebClient is created with a base URI and a redirect location is a different URI.
 ```
 
@@ -136,7 +135,7 @@ Requests can be sent with a streaming body like this:
 import cats.effect.IO
 import fs2.Stream
 import sttp.capabilities.fs2.Fs2Streams
-import sttp.client4._
+import sttp.client4.*
 import sttp.client4.httpclient.fs2.HttpClientFs2Backend
 
 val effect = HttpClientFs2Backend.resource[IO]().use { backend =>
@@ -156,7 +155,7 @@ Responses can also be streamed:
 import cats.effect.IO
 import fs2.Stream
 import sttp.capabilities.fs2.Fs2Streams
-import sttp.client4._
+import sttp.client4.*
 import sttp.client4.httpclient.fs2.HttpClientFs2Backend
 import scala.concurrent.duration.Duration
 
@@ -182,9 +181,9 @@ The fs2 backends support both regular and streaming [websockets](../websockets.m
 Received data streams can be parsed to a stream of server-sent events (SSE):
 
 ```scala
-import cats.effect._
+import cats.effect.*
 import fs2.Stream
-import sttp.client4._
+import sttp.client4.*
 import sttp.capabilities.fs2.Fs2Streams
 import sttp.client4.impl.fs2.Fs2ServerSentEvents
 import sttp.model.sse.ServerSentEvent

generated-docs/out/backends/future.md

@@ -2,17 +2,18 @@
 
 There are several backend implementations which are `scala.concurrent.Future`-based. These backends are **asynchronous**, sending a request is a non-blocking operation and results in a response wrapped in a `Future`. 
 
-Apart from the ones described below, also the [Akka](akka.md) backend is `Future`-based.
+Apart from the ones described below, also the [Pekko](pekko.md) & [Akka](akka.md) backends are `Future`-based.
 
-```eval_rst
-===================================== ================================================ ==========================
-Class                                 Supported stream type                            Websocket support
-===================================== ================================================ ==========================
-``HttpClientFutureBackend``           n/a                                              yes (regular)
-``AkkaHttpBackend``                   ``akka.stream.scaladsl.Source[ByteString, Any]`` yes (regular & streaming)
-``OkHttpFutureBackend``               n/a                                              yes (regular)
-``ArmeriaFutureBackend``              n/a                                              n/a
-===================================== ================================================ ==========================
+```{eval-rst}
+===================================== ================================================= ==========================
+Class                                 Supported stream type                             Websocket support
+===================================== ================================================= ==========================
+``HttpClientFutureBackend``           n/a                                               yes (regular)
+``PekkoHttpBackend``                  ``pekko.stream.scaladsl.Source[ByteString, Any]`` yes (regular & streaming)
+``AkkaHttpBackend``                   ``akka.stream.scaladsl.Source[ByteString, Any]``  yes (regular & streaming)
+``OkHttpFutureBackend``               n/a                                               yes (regular)
+``ArmeriaFutureBackend``              n/a                                               n/a
+===================================== ================================================= ==========================
 ```
 
 ## Using HttpClient
@@ -53,7 +54,6 @@ Host header override is supported in environments running Java 12 onwards, but i
 -Djdk.httpclient.allowRestrictedHeaders=host
 ```
 
-
 ## Using OkHttp
 
 To use, add the following dependency to your project:
@@ -112,7 +112,7 @@ ArmeriaFutureBackend.usingDefaultClient()
 or, if you'd like to instantiate the [WebClient](https://armeria.dev/docs/client-http) yourself::
 
 ```scala
-import com.linecorp.armeria.client.circuitbreaker._
+import com.linecorp.armeria.client.circuitbreaker.*
 import com.linecorp.armeria.client.WebClient
 
 // Fluently build Armeria WebClient with built-in decorators
@@ -125,7 +125,7 @@ val client = WebClient.builder("https://my-service.com")
 val backend = ArmeriaFutureBackend.usingClient(client)
 ```
 
-```eval_rst
+```{eval-rst}
 .. note:: A WebClient could fail to follow redirects if the WebClient is created with a base URI and a redirect location is a different URI.
 ```
 

generated-docs/out/backends/http4s.md

@@ -11,10 +11,10 @@ This backend is based on [http4s](https://http4s.org) (client) and is **asynchro
 The backend can be created in a couple of ways, e.g.:
 
 ```scala
-import cats.effect._
+import cats.effect.*
 import sttp.capabilities.fs2.Fs2Streams
-import sttp.client4._
-import sttp.client4.http4s._
+import sttp.client4.*
+import sttp.client4.http4s.*
 
 // the "org.http4s" %% "http4s-ember-client" % http4sVersion dependency needs to be explicitly added
 Http4sBackend.usingDefaultEmberClientBuilder[IO](): Resource[IO, StreamBackend[IO, Fs2Streams[IO]]]

generated-docs/out/backends/javascript/fetch.md

@@ -135,8 +135,8 @@ To use, add the following dependency to your project:
 An example of streaming a response:
 
 ```scala   
-import sttp.client4._
-import sttp.client4.impl.monix._
+import sttp.client4.*
+import sttp.client4.impl.monix.*
 
 import java.nio.ByteBuffer
 import monix.eval.Task
@@ -151,7 +151,7 @@ val response: Task[Response[Observable[ByteBuffer]]] =
     .send(backend)
 ```      
 
-```eval_rst
+```{eval-rst}
 .. note:: Currently no browsers support passing a stream as the request body. As such, using the ``Fetch`` backend with a streaming request will result in it being converted into an in-memory array before being sent. Response bodies are returned as a "proper" stream.
 ```
 
@@ -170,7 +170,7 @@ import monix.eval.Task
 import sttp.capabilities.monix.MonixStreams
 import sttp.client4.impl.monix.MonixServerSentEvents
 import sttp.model.sse.ServerSentEvent
-import sttp.client4._
+import sttp.client4.*
 
 def processEvents(source: Observable[ServerSentEvent]): Task[Unit] = ???