Merge pull request #19905 from mkouba/qute-standalone-docs

Qute docs - introduce the "Qute Used as a Standalone Library" section

docs/src/main/asciidoc/qute-reference.adoc

@@ -17,8 +17,12 @@ The usage of reflection is minimized to reduce the size of native images.
 The API combines both the imperative and the non-blocking reactive style of coding.
 In the development mode, all files located in the `src/main/resources/templates` folder are watched for changes and modifications are immediately visible in your application.
 Furthermore, Qute attempts to detect most of the template problems at build time and fail fast.
+
 In this guide, you will find an <<hello_world_example,introductory example>>, the description of the <<core_features,core features>> and <<quarkus_integration,Quarkus integration>> details.
 
+NOTE: Qute is primarily designed as a Quarkus extension. It is possible to use it as a "standalone" library too. However, in such case some of the features are not available. In general, any feature mentioned under the <<quarkus_integration>> section is missing. You can find more information about the limitations and possibilities in the <<standalone>> section.
+
+
 [[hello_world_example]]
 == Hello World Example
 
@@ -992,6 +996,7 @@ NOTE: The template rendering is divided in two phases. During the first phase, w
 
 === Engine Configuration
 
+[[value-resolvers]]
 ==== Value Resolvers
 
 Value resolvers are used when evaluating expressions.
@@ -1006,6 +1011,7 @@ engineBuilder.addValueResolver(ValueResolver.builder()
     .build());
 ----
 
+[[template-locator]]
 ==== Template Locator
 
 Manual registration is sometimes handy but it's also possible to register a template locator using `EngineBuilder.addLocator(Function<String, Optional<Reader>>)`.
@@ -1673,6 +1679,7 @@ WARNING: Unlike with `@Inject` the templates obtained via `RestTemplate` are not
 
 In the development mode, all files located in `src/main/resources/templates` are watched for changes and modifications are immediately visible.
 
+[[type-safe-message-bundles]]
 === Type-safe Message Bundles
 
 ==== Basic Concepts
@@ -1838,3 +1845,33 @@ public class MyBean {
 === Configuration Reference
 
 include::{generated-dir}/config/quarkus-qute.adoc[leveloffset=+1, opts=optional]
+
+
+[[standalone]]
+== Qute Used as a Standalone Library
+
+Qute is primarily designed as a Quarkus extension. 
+However. it is possible to use it as a "standalone" library.
+In this case, some features are not available and some additional configuration is needed.
+
+Engine:: First of all, no managed `Engine` instance is available out of the box.
+You'll need to configure a new instance via `Engine.builder()`.
+
+Templates:: 
+* By default, no <<template-locator,template locators>> are registered, i.e. `Engine.getTemplate(String)` will not work. 
+* You can register a custom template locator or parse a template manually and put the reulst in the cache via `Engine.putTemplate(String, Template)`.
+
+Value resolvers:: 
+* No <<value-resolvers,``ValueResolver``s>> are generated automatically.
+** <<template_extension_methods,`@TemplateExtension` methods>> will not work. 
+** <<template_data,`@TemplateData`>> annotations are ignored.
+* It's recommended to register a `ReflectionValueResolver` instance via `Engine.addValueResolver(new ReflectionValueResolver())` so that Qute can access object properties and call public methods. 
++
+NOTE: Keep in mind that reflection may not work correctly in some restricted environments or may require additional configuration, e.g. registration in case of a GraalVM native image. 
+* A custom value resolver can be easily built via `ValueResolver.builder()`
+
+Type-safety::
+* <<typesafe_expressions>> are not validated.
+* <<type-safe-message-bundles,Type-safe message bundles>> are not supported.
+
+Injection:: It is not possible to inject a `Template` instance and vice versa - a template cannot inject a `@Named` CDI bean via the `inject:` namespace.