diff --git a/generated-doc/out/.python-version b/generated-doc/out/.python-version index 47b6be3faf..e4fba21835 100644 --- a/generated-doc/out/.python-version +++ b/generated-doc/out/.python-version @@ -1 +1 @@ -3.7.2 \ No newline at end of file +3.12 diff --git a/generated-doc/out/conf.py b/generated-doc/out/conf.py index c15767a4c2..5afa049774 100644 --- a/generated-doc/out/conf.py +++ b/generated-doc/out/conf.py @@ -32,6 +32,8 @@ # ones. extensions = ['myst_parser', 'sphinx_rtd_theme'] +myst_enable_extensions = ['attrs_block'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -39,9 +41,6 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -from recommonmark.parser import CommonMarkParser -from recommonmark.transform import AutoStructify - source_suffix = { '.rst': 'restructuredtext', '.txt': 'markdown', @@ -53,7 +52,7 @@ # General information about the project. project = u'tapir' -copyright = u'2023, SoftwareMill' +copyright = u'2024, SoftwareMill' author = u'SoftwareMill' # The version info for the project you're documenting, acts as replacement for @@ -70,7 +69,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -78,7 +77,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'default' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -184,11 +183,3 @@ 'github_version': 'master', # Version 'conf_py_path': '/doc/', # Path in the checkout to the docs root } - -# app setup hook -def setup(app): - app.add_config_value('recommonmark_config', { - 'auto_toc_tree_section': 'Contents', - 'enable_auto_doc_ref': False - }, True) - app.add_transform(AutoStructify) diff --git a/generated-doc/out/docs/openapi.md b/generated-doc/out/docs/openapi.md index 670fb0a8dd..2434c0db29 100644 --- a/generated-doc/out/docs/openapi.md +++ b/generated-doc/out/docs/openapi.md @@ -239,12 +239,10 @@ security requirements will be created for them. However, this will not include t mandatory. If authentication should be optional, an empty security requirement will be added if an `emptyAuth` input is added (which doesn't map to any values in the request, but only serves as a marker). -```eval_rst -.. note:: - - Note that even though multiple optional authentication methods might be rendered as alternatives in the documentation, - when running the server, you'll need to additionally check that at least one authentication input is provided. This - can be done in the security logic, server logic, or by mapping the inputs using .mapDecode, as in the below example: +```{note} +Note that even though multiple optional authentication methods might be rendered as alternatives in the documentation, +when running the server, you'll need to additionally check that at least one authentication input is provided. This +can be done in the security logic, server logic, or by mapping the inputs using .mapDecode, as in the below example: ``` ```scala diff --git a/generated-doc/out/endpoint/basics.md b/generated-doc/out/endpoint/basics.md index b48fe41fe1..d1e9038f30 100644 --- a/generated-doc/out/endpoint/basics.md +++ b/generated-doc/out/endpoint/basics.md @@ -43,7 +43,7 @@ val userEndpoint: PublicEndpoint[(UUID, Int), String, User, Any] = ??? You can think of an endpoint as a function which takes input parameters of type `A` and `I` and returns a result of type `Either[E, O]`. -### Infallible endpoints +## Infallible endpoints Note that the empty `endpoint` description maps no values to either error and success outputs, however errors are still represented and allowed to occur. In case of the error output, the single member of the unit type, `(): Unit`, diff --git a/generated-doc/out/endpoint/customtypes.md b/generated-doc/out/endpoint/customtypes.md index 3a4ae194e5..1449a1b01d 100644 --- a/generated-doc/out/endpoint/customtypes.md +++ b/generated-doc/out/endpoint/customtypes.md @@ -80,12 +80,10 @@ import sttp.tapir.Codec.PlainCodec implicit val myIdCodec: PlainCodec[MyId] = Codec.string.mapDecode(decode)(encode) ``` -```eval_rst -.. note:: - - Note that inputs/outputs can also be mapped over. In some cases, it's enough to create an input/output corresponding - to one of the existing types, and then map over them. However, if you have a type that's used multiple times, it's - usually better to define a codec for that type. +```{note} +Note that inputs/outputs can also be mapped over. In some cases, it's enough to create an input/output corresponding +to one of the existing types, and then map over them. However, if you have a type that's used multiple times, it's +usually better to define a codec for that type. ``` Then, you can use the new codec; e.g. to obtain an id from a query parameter, or a path segment: diff --git a/generated-doc/out/endpoint/enumerations.md b/generated-doc/out/endpoint/enumerations.md index 46c5e4402b..b1d74606f1 100644 --- a/generated-doc/out/endpoint/enumerations.md +++ b/generated-doc/out/endpoint/enumerations.md @@ -150,12 +150,10 @@ properly represented in [OpenAPI](../docs/openapi.md) documentation. You can take a look at a runnable example [here](https://github.com/softwaremill/tapir/tree/master/examples/src/main/scala/sttp/tapir/examples/custom_types). -```eval_rst -.. warning:: - - ``Delimited`` and ``CommaSeparated`` rely on literal types, which are only available in Scala 2.13+. +```{warning} +`Delimited` and `CommaSeparated` rely on literal types, which are only available in Scala 2.13+. - If you're using an older version of Scala, a workaround is creating a comma-separated codec locally. +If you're using an older version of Scala, a workaround is creating a comma-separated codec locally. ``` ## Using enumerations as part of bodies @@ -272,4 +270,4 @@ is that an enumeration [validator](validation.md) has to be added to the schema. ## Next -Read on about [validation](validation.md). \ No newline at end of file +Read on about [validation](validation.md). diff --git a/generated-doc/out/endpoint/integrations.md b/generated-doc/out/endpoint/integrations.md index d6ad5ef70b..8f1f661864 100644 --- a/generated-doc/out/endpoint/integrations.md +++ b/generated-doc/out/endpoint/integrations.md @@ -1,11 +1,9 @@ # Datatypes integrations -```eval_rst -.. note:: - - Note that the codecs defined by the tapir integrations are used only when the specific types (e.g. enumerations) are - used at the top level. Any nested usages (e.g. as part of a json body), need to be separately configured to work with - the used json library. +```{note} +Note that the codecs defined by the tapir integrations are used only when the specific types (e.g. enumerations) are +used at the top level. Any nested usages (e.g. as part of a json body), need to be separately configured to work with +the used json library. ``` ## Cats datatypes integration diff --git a/generated-doc/out/endpoint/json.md b/generated-doc/out/endpoint/json.md index b458a6beb4..2c260f62d3 100644 --- a/generated-doc/out/endpoint/json.md +++ b/generated-doc/out/endpoint/json.md @@ -11,13 +11,11 @@ an implicit `Schema[T]` instance, which can be automatically derived. For more d [schema derivation](schemas.md) and on supporting [custom types](customtypes.md) in general. Such a design provides better error reporting, in case one of the components required to create the json codec is missing. -```eval_rst -.. note:: - - Note that the process of deriving schemas, and deriving library-specific json encoders and decoders is entirely - separate (unless you're using the pickler module - see below). The first is controlled by tapir, the second - by the - json library. Any customisation, e.g. for field naming or inheritance strategies, must be done separately for both - derivations. +```{note} +Note that the process of deriving schemas, and deriving library-specific json encoders and decoders is entirely +separate (unless you're using the pickler module - see below). The first is controlled by tapir, the second - by the +json library. Any customisation, e.g. for field naming or inheritance strategies, must be done separately for both +derivations. ``` ## Pickler diff --git a/generated-doc/out/endpoint/oneof.md b/generated-doc/out/endpoint/oneof.md index f7e279e3b3..4478ca4045 100644 --- a/generated-doc/out/endpoint/oneof.md +++ b/generated-doc/out/endpoint/oneof.md @@ -5,15 +5,13 @@ There are two kind of one-of inputs/outputs: * `oneOf` outputs where the arbitrary-output variants can represent different content using different outputs, and * `oneOfBody` input/output where the body-only variants represent the same content, but with different content types -```eval_rst -.. note:: - - ``oneOf`` and ``oneOfBody`` outputs are not related to ``oneOf:`` schemas when - `generating `_ OpenAPI documentation. - - Such schemas are generated for coproducts - e.g. ``sealed trait`` families - given an appropriate codec. See the - documentation on - `coproducts `_ for details. +```{note} +`oneOf` and `oneOfBody` outputs are not related to `oneOf:` schemas when +[generating](https://tapir.softwaremill.com/en/latest/docs/openapi.html) OpenAPI documentation. + +Such schemas are generated for coproducts - e.g. `sealed trait` families - given an appropriate codec. See the +documentation on [coproducts](https://tapir.softwaremill.com/en/latest/endpoint/schemas.html#sealed-traits-coproducts) +for details. ``` ## `oneOf` outputs @@ -218,17 +216,13 @@ on streaming bodies, which "lifts" them to an `EndpointIO` type, forgetting the type safety, as a run-time error might occur if an incompatible interpreter is used, however allows describing endpoints which require including streaming bodies in output variants. -```eval_rst -.. note:: - - If the same streaming body description is used in all branches of a ``oneOf``, this can be refactored into - a regular streaming body output + a varying set of output headers, expressed using ``oneOf``. +```{note} +If the same streaming body description is used in all branches of a `oneOf`, this can be refactored into +a regular streaming body output + a varying set of output headers, expressed using `oneOf`. ``` -```eval_rst -.. warning:: - - Mixed streaming and non-streaming bodies defined as ``oneOf`` variants currently won't work with client interpreters. +```{warning} +Mixed streaming and non-streaming bodies defined as `oneOf` variants currently won't work with client interpreters. ``` ## Next diff --git a/generated-doc/out/endpoint/schemas.md b/generated-doc/out/endpoint/schemas.md index 4157175f78..f0a66a2361 100644 --- a/generated-doc/out/endpoint/schemas.md +++ b/generated-doc/out/endpoint/schemas.md @@ -149,16 +149,14 @@ implicit val anotherSchemaForMyCustomType: Schema[MyCustomType] = Schema(SchemaT Schema derivation for coproduct types (sealed hierarchies) is supported as well. By default, such hierarchies will be represented as a coproduct which contains a list of child schemas, without any discriminators. -```eval_rst -.. note:: - - Note that whichever approach you choose to define the coproduct schema, it has to match the way the value is - encoded and decoded by the codec. E.g. when the schema is for a json body, the discriminator must be separately - configured in the json library, matching the configuration of the schema. - - Alternatively, instead of deriving schemas and json codecs separately, you can use the experimental - `pickler `_ - module, which provides a higher level ``Pickler`` concept, which takes care of consistent derivation. +```{note} +Note that whichever approach you choose to define the coproduct schema, it has to match the way the value is +encoded and decoded by the codec. E.g. when the schema is for a json body, the discriminator must be separately +configured in the json library, matching the configuration of the schema. + +Alternatively, instead of deriving schemas and json codecs separately, you can use the experimental +[pickler](https://tapir.softwaremill.com/en/latest/endpoint/pickler.html) +module, which provides a higher level `Pickler` concept, which takes care of consistent derivation. ``` ### Field discriminators diff --git a/generated-doc/out/endpoint/security.md b/generated-doc/out/endpoint/security.md index e5a0e1bf6f..08207affbc 100644 --- a/generated-doc/out/endpoint/security.md +++ b/generated-doc/out/endpoint/security.md @@ -15,12 +15,10 @@ Inputs which map to authentication credentials can be created using methods avai inputs in addition to the base input (such as an `Authorization` header or a cookie), contain security-related metadata, for example the name of the security scheme that should be used for documentation. -```eval_rst -.. note:: - - Note that security inputs added using ``.securityIn`` can contain both dedicated auth credentials inputs created - using one of the methods from ``auth``, and arbitrary "regular" inputs, such as path components. Similarly, regular - inputs can contain inputs created through ``auth``, though typically this shouldn't be the case. +```{note} +Note that security inputs added using `.securityIn` can contain both dedicated auth credentials inputs created +using one of the methods from `auth`, and arbitrary "regular" inputs, such as path components. Similarly, regular +inputs can contain inputs created through `auth`, though typically this shouldn't be the case. ``` Currently, the following authentication inputs are available (assuming `import sttp.tapir._`): diff --git a/generated-doc/out/endpoint/static.md b/generated-doc/out/endpoint/static.md index 6e10b59fa1..e6bb242f2f 100644 --- a/generated-doc/out/endpoint/static.md +++ b/generated-doc/out/endpoint/static.md @@ -3,10 +3,9 @@ Tapir contains predefined endpoints, server logic and server endpoints which allow serving static content, originating from local files or application resources. These endpoints respect etags, byte ranges as well as if-modified-since headers. -```eval_rst -.. note:: - Since Tapir 1.3.0, static content is supported via the new `tapir-files` module. If you're looking for - the API documentation of the old static content API, switch documentation to an older version. +```{note} +Since Tapir 1.3.0, static content is supported via the new `tapir-files` module. If you're looking for +the API documentation of the old static content API, switch documentation to an older version. ``` In order to use static content endpoints, add the module to your dependencies: diff --git a/generated-doc/out/endpoint/streaming.md b/generated-doc/out/endpoint/streaming.md index e7357c9f6e..3bc9b7e1cf 100644 --- a/generated-doc/out/endpoint/streaming.md +++ b/generated-doc/out/endpoint/streaming.md @@ -5,13 +5,11 @@ must implement the `Streams[S]` capability, and determines the precise type of t non-blocking streams implementation. The interpreter must then support the given capability. Refer to the documentation of server/client interpreters for more information. -```eval_rst -.. note:: - - Here, streams refer to asynchronous, non-blocking, "reactive" stream implementations, such as `akka-streams `_, - `fs2 `_ or `zio-streams `_. If you'd like to use - blocking streams (such as ``InputStream``), these are available through e.g. ``inputStreamBody`` without any - additional requirements on the interpreter. +```{note} +Here, streams refer to asynchronous, non-blocking, "reactive" stream implementations, such as [akka-streams](https://doc.akka.io/docs/akka/current/stream/index.html), +[fs2](https://fs2.io) or [zio-streams](https://zio.dev/docs/datatypes/datatypes_stream). If you'd like to use +blocking streams (such as `InputStream`), these are available through e.g. `inputStreamBody` without any +additional requirements on the interpreter. ``` Adding a stream body input/output influences both the type of the input/output, as well as the 5th type parameter @@ -45,4 +43,4 @@ See also the [runnable streaming example](../examples.md). ## Next -Read on about [web sockets](websockets.md). \ No newline at end of file +Read on about [web sockets](websockets.md). diff --git a/generated-doc/out/endpoint/xml.md b/generated-doc/out/endpoint/xml.md index a6e08c6bee..4ad792cda0 100644 --- a/generated-doc/out/endpoint/xml.md +++ b/generated-doc/out/endpoint/xml.md @@ -4,14 +4,12 @@ Enabling support for XML is a matter of implementing proper [`XmlCodec[T]`](code This enables encoding objects to XML strings, and decoding XML strings to objects. Implementation is fairly easy, and for now, one guide on how to integrate with scalaxb is provided. -```eval_rst -.. note:: - - Note, that implementing ``XmlCodec[T]`` would require deriving not only XML library encoders/decoders, - but also tapir related ``Schema[T]``. These are completely separate - any customization e.g. for field - naming or inheritance strategies must be done separately for both derivations. - For more details see sections on `schema derivation `_ - and on supporting `custom types `_ in general. +```{note} +Note, that implementing `XmlCodec[T]` would require deriving not only XML library encoders/decoders, +but also tapir related `Schema[T]`. These are completely separate - any customization e.g. for field +naming or inheritance strategies must be done separately for both derivations. +For more details see sections on [schema derivation](schemas.md) and on supporting [custom types](customtypes.md) in +general. ``` ## Scalaxb diff --git a/generated-doc/out/generator/sbt-openapi-codegen.md b/generated-doc/out/generator/sbt-openapi-codegen.md index 316a73a948..04619f5d53 100644 --- a/generated-doc/out/generator/sbt-openapi-codegen.md +++ b/generated-doc/out/generator/sbt-openapi-codegen.md @@ -1,9 +1,7 @@ # Generate endpoint definitions from an OpenAPI YAML -```eval_rst -.. note:: - - This is a really early alpha implementation. +```{note} +This is a really early alpha implementation. ``` ## Installation steps @@ -34,7 +32,7 @@ defined case-classes and endpoint definitions. The generator currently supports these settings, you can override them in the `build.sbt`; -```eval_rst +```{eval-rst} ===================================== ==================================== ================================================================================================== setting default value description ===================================== ==================================== ================================================================================================== @@ -92,7 +90,7 @@ having no tags, would be output to the `TapirGeneratedEndpoints` file, along wit ### Json Support -```eval_rst +```{eval-rst} ===================== ================================================================== =================================================================== openapiJsonSerdeLib required dependencies Conditional requirements ===================== ================================================================== =================================================================== diff --git a/generated-doc/out/index.md b/generated-doc/out/index.md index 8746690d7b..2b1939a971 100644 --- a/generated-doc/out/index.md +++ b/generated-doc/out/index.md @@ -49,7 +49,7 @@ for a more detailed description of how tapir works! ScalaDocs are available at [ ## Adopt a tapir -```eval_rst +```{eval-rst} .. raw:: html