=doc,htc #19252 fix docs where occasionally broken

akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst

@@ -1,8 +1,8 @@
 .. _migration-2.0-java:
 
-############################
+##########################
 Migration Guide 1.0 to 2.x
-############################
+##########################
 
 The 2.0 release contains some structural changes that require some
 simple, mechanical source-level changes in client code. While these are detailed below,
@@ -80,6 +80,7 @@ Update procedure
    ``BidiFlow.fromFlows`` or ``BidiFlow.fromFlowsMat``
 5. Replace all uses of ``BidiFlow.apply()`` (Scala DSL) or ``BidiFlow.create()`` (Java DSL) when it converts two
    functions to a ``BidiFlow`` with ``BidiFlow.fromFunctions``
+
 Example
 ^^^^^^^
 
@@ -122,7 +123,7 @@ Should be replaced by
 
 
 Renamed ``inlet()`` and ``outlet()`` to ``in()`` and ``out()`` in ``SourceShape``, ``SinkShape`` and ``FlowShape``
-==========================================================================================================
+==================================================================================================================
 
 The input and output ports of these shapes where called ``inlet()`` and ``outlet()`` compared to other shapes that
 consistently used ``in()`` and ``out()``. Now all :class:`Shape` s use ``in()`` and ``out()``.

akka-docs-dev/rst/java/stream-graphs.rst

@@ -194,8 +194,8 @@ turns an object into a sequence of bytes.
 
 The other stage that we talked about is a little more involved since reversing
 a framing protocol means that any received chunk of bytes may correspond to
-zero or more messages. This is best implemented using a :class:`PushPullStage`
+zero or more messages. This is best implemented using a :class:`GraphStage`
-(see also :ref:`stream-using-push-pull-stage-java`).
+(see also :ref:`graphstage-java`).
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/BidiFlowDocTest.java#framing
 

akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala

@@ -22,6 +22,7 @@ import scala.util.control.NonFatal
 
 class BasicDirectivesExamplesSpec extends RoutingSpec {
   "0extract" in {
+    //#0extract
     val uriLength = extract(_.request.uri.toString.length)
     val route =
       uriLength { len =>
@@ -32,8 +33,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abcdef") ~> route ~> check {
       responseAs[String] shouldEqual "The length of the request URI is 25"
     }
+    //#0extract
   }
   "0extractLog" in {
+    //#0extractLog
     val route =
       extractLog { log =>
         log.debug("I'm logging things in much detail..!")
@@ -44,8 +47,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abcdef") ~> route ~> check {
       responseAs[String] shouldEqual "It's amazing!"
     }
+    //#0extractLog
   }
   "withMaterializer-0" in {
+    //#withMaterializer-0
     val special = ActorMaterializer(namePrefix = Some("special"))
 
     def sample() =
@@ -73,8 +78,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/special/sample") ~> route ~> check {
       responseAs[String] shouldEqual s"Materialized by ${special.##}!"
     }
+    //#withMaterializer-0
   }
   "extractMaterializer-0" in {
+    //#extractMaterializer-0
     val route =
       path("sample") {
         extractMaterializer { materializer =>
@@ -90,8 +97,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/sample") ~> route ~> check {
       responseAs[String] shouldEqual s"Materialized by ${materializer.##}!"
     }
+    //#extractMaterializer-0
   }
   "withExecutionContext-0" in compileOnlySpec {
+    //#withExecutionContext-0
     val special = system.dispatchers.lookup("special")
 
     def sample() =
@@ -117,8 +126,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/special/sample") ~> route ~> check {
       responseAs[String] shouldEqual s"Run on ${special.##}!"
     }
+    //#withExecutionContext-0
   }
   "extractExecutionContext-0" in compileOnlySpec {
+    //#extractExecutionContext-0
     def sample() =
       path("sample") {
         extractExecutionContext { implicit ec =>
@@ -137,8 +148,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/sample") ~> route ~> check {
       responseAs[String] shouldEqual s"Run on ${system.dispatcher.##}!"
     }
+    //#extractExecutionContext-0
   }
   "0withLog" in {
+    //#0withLog
     val special = Logging(system, "SpecialRoutes")
 
     def sample() =
@@ -166,8 +179,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/special/sample") ~> route ~> check {
       responseAs[String] shouldEqual s"Logging using $special!"
     }
+    //#0withLog
   }
   "withSettings-0" in compileOnlySpec {
+    //#withSettings-0
     val special = RoutingSettings(system).copy(fileIODispatcher = "special-io-dispatcher")
 
     def sample() =
@@ -195,8 +210,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/sample") ~> route ~> check {
       responseAs[String] shouldEqual "{}"
     }
+    //#withSettings-0
   }
   "textract" in {
+    //#textract
     val pathAndQuery = textract { ctx =>
       val uri = ctx.request.uri
       (uri.path, uri.query())
@@ -210,8 +227,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abcdef?ghi=12") ~> route ~> check {
       responseAs[String] shouldEqual "The path is /abcdef and the query is ghi=12"
     }
+    //#textract
   }
   "tprovide" in {
+    //#tprovide
     def provideStringAndLength(value: String) = tprovide((value, value.length))
     val route =
       provideStringAndLength("test") { (value, len) =>
@@ -222,8 +241,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "Value is test and its length is 4"
     }
+    //#tprovide
   }
   "0mapResponse" in {
+    //#0mapResponse
     def overwriteResultStatus(response: HttpResponse): HttpResponse =
       response.copy(status = StatusCodes.BadGateway)
     val route = mapResponse(overwriteResultStatus)(complete("abc"))
@@ -232,6 +253,7 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abcdef?ghi=12") ~> route ~> check {
       status shouldEqual StatusCodes.BadGateway
     }
+    //#0mapResponse
   }
   "1mapResponse-advanced-json" in {
     //#1mapResponse-advanced
@@ -277,6 +299,7 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     //#1mapResponse-advanced
   }
   "mapRouteResult" in {
+    //#mapRouteResult
     // this directive is a joke, don't do that :-)
     val makeEverythingOk = mapRouteResult { r =>
       r match {
@@ -297,8 +320,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       status shouldEqual StatusCodes.OK
     }
+    //#mapRouteResult
   }
   "mapRouteResultFuture" in {
+    //#mapRouteResultFuture
     val tryRecoverAddServer = mapRouteResultFuture { fr =>
       fr recover {
         case ex: IllegalArgumentException =>
@@ -319,8 +344,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       status shouldEqual StatusCodes.OK
       header[Server] shouldEqual Some(Server("MyServer 1.0"))
     }
+    //#mapRouteResultFuture
   }
   "mapResponseEntity" in {
+    //#mapResponseEntity
     def prefixEntity(entity: ResponseEntity): ResponseEntity = entity match {
       case HttpEntity.Strict(contentType, data) =>
         HttpEntity.Strict(contentType, ByteString("test") ++ data)
@@ -334,8 +361,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "testabc"
     }
+    //#mapResponseEntity
   }
   "mapResponseHeaders" in {
+    //#mapResponseHeaders
     // adds all request headers to the response
     val echoRequestHeaders = extract(_.request.headers).flatMap(respondWithHeaders)
 
@@ -352,8 +381,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       header("id") shouldEqual None
       header("id2").get.value shouldEqual "67890"
     }
+    //#mapResponseHeaders
   }
   "mapInnerRoute" in {
+    //#mapInnerRoute
     val completeWithInnerException =
       mapInnerRoute { route =>
         ctx =>
@@ -373,8 +404,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "Got IllegalArgumentException 'BLIP! BLOP! Everything broke'"
     }
+    //#mapInnerRoute
   }
   "mapRejections" in {
+    //#mapRejections
     // ignore any rejections and replace them by AuthorizationFailedRejection
     val replaceByAuthorizationFailed = mapRejections(_ => List(AuthorizationFailedRejection))
     val route =
@@ -390,8 +423,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abc") ~> route ~> check {
       status shouldEqual StatusCodes.OK
     }
+    //#mapRejections
   }
   "recoverRejections" in {
+    //#recoverRejections
     val authRejectionsToNothingToSeeHere = recoverRejections { rejections =>
       if (rejections.exists(_.isInstanceOf[AuthenticationFailedRejection]))
         Complete(HttpResponse(entity = "Nothing to see here, move along."))
@@ -432,8 +467,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       status shouldEqual StatusCodes.NotFound
       responseAs[String] shouldEqual "Literally nothing to see here."
     }
+    //#recoverRejections
   }
   "recoverRejectionsWith" in {
+    //#recoverRejectionsWith
     val authRejectionsToNothingToSeeHere = recoverRejectionsWith { rejections =>
       Future {
         // imagine checking rejections takes a longer time:
@@ -461,8 +498,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       status shouldEqual StatusCodes.OK
       responseAs[String] shouldEqual "Nothing to see here, move along."
     }
+    //#recoverRejectionsWith
   }
   "0mapRequest" in {
+    //#0mapRequest
     def transformToPostRequest(req: HttpRequest): HttpRequest = req.copy(method = HttpMethods.POST)
     val route =
       mapRequest(transformToPostRequest) {
@@ -474,8 +513,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "The request method was POST"
     }
+    //#0mapRequest
   }
   "mapRequestContext" in {
+    //#mapRequestContext
     val replaceRequest =
       mapRequestContext(_.withRequest(HttpRequest(HttpMethods.POST)))
 
@@ -490,8 +531,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abc/def/ghi") ~> route ~> check {
       responseAs[String] shouldEqual "POST"
     }
+    //#mapRequestContext
   }
   "0mapRouteResult" in {
+    //#0mapRouteResult
     val rejectAll = // not particularly useful directive
       mapRouteResult {
         case _ => Rejected(List(AuthorizationFailedRejection))
@@ -505,8 +548,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       rejections.nonEmpty shouldEqual true
     }
+    //#0mapRouteResult
   }
   "mapRouteResultPF" in {
+    //#mapRouteResultPF
     case object MyCustomRejection extends Rejection
     val rejectRejections = // not particularly useful directive
       mapRouteResultPF {
@@ -521,8 +566,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       rejection shouldEqual AuthorizationFailedRejection
     }
+    //#mapRouteResultPF
   }
   "mapRouteResultWithPF-0" in {
+    //#mapRouteResultWithPF-0
     case object MyCustomRejection extends Rejection
     val rejectRejections = // not particularly useful directive
       mapRouteResultWithPF {
@@ -537,8 +584,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       rejection shouldEqual AuthorizationFailedRejection
     }
+    //#mapRouteResultWithPF-0
   }
   "mapRouteResultWith-0" in {
+    //#mapRouteResultWith-0
     case object MyCustomRejection extends Rejection
     val rejectRejections = // not particularly useful directive
       mapRouteResultWith { res =>
@@ -556,16 +605,20 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       rejection shouldEqual AuthorizationFailedRejection
     }
+    //#mapRouteResultWith-0
   }
   "pass" in {
+    //#pass
     val route = pass(complete("abc"))
 
     // tests:
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "abc"
     }
+    //#pass
   }
   "0provide" in {
+    //#0provide
     def providePrefixedString(value: String): Directive1[String] = provide("prefix:" + value)
     val route =
       providePrefixedString("test") { value =>
@@ -576,8 +629,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "prefix:test"
     }
+    //#0provide
   }
   "cancelRejections-filter-example" in {
+    //#cancelRejections-filter-example
     def isMethodRejection: Rejection => Boolean = {
       case MethodRejection(_) => true
       case _                  => false
@@ -595,8 +650,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       rejections shouldEqual Nil
       handled shouldEqual false
     }
+    //#cancelRejections-filter-example
   }
   "cancelRejection-example" in {
+    //#cancelRejection-example
     val route =
       cancelRejection(MethodRejection(HttpMethods.POST)) {
         post {
@@ -609,8 +666,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       rejections shouldEqual Nil
       handled shouldEqual false
     }
+    //#cancelRejection-example
   }
   "extractRequest-example" in {
+    //#extractRequest-example
     val route =
       extractRequest { request =>
         complete(s"Request method is ${request.method.name} and content-type is ${request.entity.contentType}")
@@ -623,8 +682,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "Request method is GET and content-type is none/none"
     }
+    //#extractRequest-example
   }
   "extractSettings-examples" in {
+    //#extractSettings-examples
     val route =
       extractSettings { settings: RoutingSettings =>
         complete(s"RoutingSettings.renderVanityFooter = ${settings.renderVanityFooter}")
@@ -634,8 +695,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual s"RoutingSettings.renderVanityFooter = true"
     }
+    //#extractSettings-examples
   }
   "mapSettings-examples" in {
+    //#mapSettings-examples
     val tunedSettings = mapSettings { settings =>
       settings.copy(fileGetConditional = false)
     }
@@ -651,8 +714,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual s"RoutingSettings.fileGetConditional = false"
     }
+    //#mapSettings-examples
   }
   "extractRequestContext-example" in {
+    //#extractRequestContext-example
     val route =
       extractRequestContext { ctx =>
         ctx.log.debug("Using access to additional context availablethings, like the logger.")
@@ -667,8 +732,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       responseAs[String] shouldEqual "Request method is GET and content-type is none/none"
     }
+    //#extractRequestContext-example
   }
   "extractUri-example" in {
+    //#extractUri-example
     val route =
       extractUri { uri =>
         complete(s"Full URI: $uri")
@@ -682,8 +749,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/test") ~> route ~> check {
       responseAs[String] shouldEqual "Full URI: http://example.com/test"
     }
+    //#extractUri-example
   }
   "mapUnmatchedPath-example" in {
+    //#mapUnmatchedPath-example
     def ignore456(path: Uri.Path) = path match {
       case s @ Uri.Path.Segment(head, tail) if head.startsWith("456") =>
         val newHead = head.drop(3)
@@ -709,8 +778,10 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/123456/abc") ~> route ~> check {
       responseAs[String] shouldEqual "Content"
     }
+    //#mapUnmatchedPath-example
   }
   "extractUnmatchedPath-example" in {
+    //#extractUnmatchedPath-example
     val route =
       pathPrefix("abc") {
         extractUnmatchedPath { remaining =>
@@ -725,6 +796,7 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/abc/456") ~> route ~> check {
       responseAs[String] shouldEqual "Unmatched: '/456'"
     }
+    //#extractUnmatchedPath-example
   }
 
   private def compileOnlySpec(block: => Unit) = pending

akka-docs-dev/rst/scala/http/common/http-model.rst

@@ -294,21 +294,21 @@ Because of the number of ways one may interact with headers (i.e. try to match a
 or the other way around etc), a helper trait for custom Header types and their companions classes are provided by Akka HTTP.
 Thanks to extending :class:`ModeledCustomHeader` instead of the plain ``CustomHeader`` such header can be matched
 
-.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/CustomHeaderRoutingSpec.scala
+.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/ModeledCustomHeaderSpec.scala
    :include: modeled-api-key-custom-header
 
 Which allows the this CustomHeader to be used in the following scenarios:
 
-.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/CustomHeaderRoutingSpec.scala
+.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/ModeledCustomHeaderSpec.scala
    :include: matching-examples
 
 Including usage within the header directives like in the following :ref:`-headerValuePF-` example:
 
-.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/CustomHeaderRoutingSpec.scala
+.. includecode:: ../../../../../akka-http-tests/src/test/scala/akka/http/scaladsl/server/ModeledCustomHeaderSpec.scala
    :include: matching-in-routes
 
 One can also directly extend :class:`CustomHeader` which requires less boilerplate, however that has the downside of
-matching against :ref:`RawHeader` instances not working out-of-the-box, thus limiting its usefulnes in the routing layer
+matching against :class:`RawHeader` instances not working out-of-the-box, thus limiting its usefulnes in the routing layer
 of Akka HTTP. For only rendering such header however it would be enough.
 
 .. note::

akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/pass.rst

@@ -13,13 +13,10 @@ Description
 -----------
 A directive that passes the request unchanged to its inner route.
 
-
 It is usually used as a "neutral element" when combining directives generically.
 
-
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
    :snippet: pass
-

akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst

@@ -1,8 +1,8 @@
 .. _migration-2.0-scala:
 
-############################
+##########################
 Migration Guide 1.0 to 2.x
-############################
+##########################
 
 The 2.0 release contains some structural changes that require some
 simple, mechanical source-level changes in client code. While these are detailed below,
@@ -128,7 +128,7 @@ Should be replaced by
 .. includecode:: code/docs/MigrationsScala.scala#bidiflow-wrap
 
 FlowGraph class and builder methods have been renamed
-===========================================
+=====================================================
 
 Due to incorrect overlap with the :class:`Flow` concept we renamed the :class:`FlowGraph` class to :class:`GraphDSL`.
 There is now only one graph creation method called ``create`` which is analogous to the old ``partial`` method. For
@@ -473,7 +473,7 @@ Update procedure
 1. All custom shapes must use ``@uncheckedVariance`` on their ``Inlet`` and ``Outlet`` members.
 
 Renamed ``inlet()`` and ``outlet()`` to ``in()`` and ``out()`` in ``SourceShape``, ``SinkShape`` and ``FlowShape``
-==========================================================================================================
+==================================================================================================================
 
 The input and output ports of these shapes where called ``inlet()`` and ``outlet()`` compared to other shapes that
 consistently used ``in()`` and ``out()``. Now all :class:`Shape` s use ``in()`` and ``out()``.

akka-docs-dev/rst/scala/stream-graphs.rst

@@ -91,7 +91,7 @@ Sometimes it is not possible (or needed) to construct the entire computation gra
 all of its different phases in different places and in the end connect them all into a complete graph and run it.
 
 This can be achieved by returning a different ``Shape`` than ``ClosedShape``, for example ``FlowShape(in, out)``, from the
-function given to ``GraphDSL.create``. See :ref:`predefined_shapes`) for a list of such predefined shapes.
+function given to ``GraphDSL.create``. See :ref:`predefined-shapes`) for a list of such predefined shapes.
 
 Making a ``Graph`` a :class:`RunnableGraph` requires all ports to be connected, and if they are not
 it will throw an exception at construction time, which helps to avoid simple
@@ -180,9 +180,14 @@ of type ``O``. To represent this interface, we need to define a custom :class:`S
 
 .. includecode:: code/docs/stream/FlowGraphDocSpec.scala#flow-graph-components-shape
 
+.. _predefined-shapes:
+
+Predefined shapes
+-----------------
+
 In general a custom :class:`Shape` needs to be able to provide all its input and output ports, be able to copy itself, and also be
 able to create a new instance from given ports. There are some predefined shapes provided to avoid unnecessary
-boilerplate
+boilerplate:
 
  * :class:`SourceShape`, :class:`SinkShape`, :class:`FlowShape` for simpler shapes,
  * :class:`UniformFanInShape` and :class:`UniformFanOutShape` for junctions with multiple input (or output) ports
@@ -246,8 +251,8 @@ turns an object into a sequence of bytes.
 
 The other stage that we talked about is a little more involved since reversing
 a framing protocol means that any received chunk of bytes may correspond to
-zero or more messages. This is best implemented using a :class:`PushPullStage`
+zero or more messages. This is best implemented using a :class:`GraphStage`
-(see also :ref:`stream-using-push-pull-stage-scala`).
+(see also :ref:`graphstage-scala`).
 
 .. includecode:: code/docs/stream/BidiFlowDocSpec.scala#framing
 

akka-docs-dev/rst/scala/stream-io.rst

@@ -96,7 +96,7 @@ logic in Flows and attaching those to :class:`StreamIO` in order to implement yo
 
 In this example both client and server may need to close the stream based on a parsed command - ``BYE`` in the case
 of the server, and ``q`` in the case of the client. This is implemented by using a custom :class:`PushStage`
-(see :ref:`stream-using-push-pull-stage-scala`) which completes the stream once it encounters such command.
+which completes the stream once it encounters such command.
 
 Streaming File IO
 =================