slachiewicz opened a new issue, #736:
URL: https://github.com/apache/maven-doxia-sitetools/issues/736
### Problem
A Doxia parser that needs anything about the project or the site has no way
to get it from Sitetools, so it injects Maven components. The Asciidoctor
parser injects `MavenProject` for three things: the project properties, the
project base directory, and the Site Plugin's own `site` goal configuration
(`MavenProject.getGoalConfiguration(...)`, where its `<asciidoc>` block lives).
That has two consequences:
- `site:run` renders documents on other threads than the Mojo thread, where
`MavenProject` (mojo execution scope) cannot be injected, so every Asciidoctor
page fails with `OutOfScopeException` (apache/maven-site-plugin#987).
apache/maven-site-plugin#1350 works around it by rendering on the Mojo thread.
- Parsers are tied to Maven's DI scopes although Doxia itself is independent
of Maven.
DOXIASITETOOLS-357 (#302, closed as stale) asked for a related piece, the
output path of the current document, which Asciidoctor extensions such as
asciidoctor-diagram need.
`Parser.parse(Reader, Sink, String reference)` carries no context. The data
already exists in Sitetools: `SiteRenderingContext` has the template properties
(the Site Plugin puts the project properties there), `getRootDirectory()`,
`getSiteDirectories()`, the locale, the encodings, the site model and, since
2.1.0, a free-form attributes map; `DocumentRenderingContext` has the base
directory, input path, output name and the document attributes.
`ParserConfigurator` (DOXIASITETOOLS-324) is already called once per document
with the parser.
### Proposed design
1. **A read-only context for parsers.** A new interface in
`doxia-site-renderer`, for example:
```java
public interface ParserRenderingContext {
Path getSourceFile(); // absolute path of the document
being parsed
Path getOutputFile(); // absolute path of the rendered
document (DOXIASITETOOLS-357)
Path getSiteDirectory(); // the site source directory the
document belongs to
Locale getLocale();
String getInputEncoding();
String getOutputEncoding();
Map<String, String> getProperties(); // string-valued template
properties, project properties included
Map<String, Object> getAttributes(); // SiteRenderingContext
attributes, set by the caller
}
```
It is a view over `DocumentRenderingContext` and `SiteRenderingContext`,
so parsers do not get the mutable contexts.
2. **An opt-in interface for parsers**, for example
`RenderingContextAwareParser` with `void
setRenderingContext(ParserRenderingContext context)`.
`DefaultSiteRenderer.renderDocument(...)` calls it right after
`doxia.getParser(...)` and before the `ParserConfigurator`. Parsers are looked
up per document, so per-document state is safe.
3. **Parser-specific configuration.** The Site Plugin puts its `site` goal
configuration into the attributes map under a documented key, so that a parser
like Asciidoctor finds its `<asciidoc>` block without `MavenProject`.
Alternatives are listed below.
4. **Threading contract.** Document that `renderDocument(...)` may run on a
thread other than the one that created the `SiteRenderingContext` (as in
`site:run`), and that parsers must not rely on Maven's mojo execution scope.
### Compatibility
Additive. A parser implementing the new interface can still inject Maven
components as a fallback when it runs with an older Sitetools or Site Plugin.
Old parsers keep working unchanged.
### Open questions
- Configuration source for item 3: the Site Plugin's goal configuration in
the attributes map (closest to what Asciidoctor reads today, but the value is a
Plexus `Xpp3Dom`), a plain `Map<String, String>` per parser id from a new Site
Plugin parameter, or the `<custom>` element of the site descriptor
(Maven-independent, already in `SiteModel`).
- A view interface as above, or simply passing `DocumentRenderingContext`
and `SiteRenderingContext` to the parser.
- Names.
### Plan once agreed
1. Sitetools: the interfaces, the call in `DefaultSiteRenderer`, a test with
a context-aware test parser.
2. Site Plugin: set the attributes and bump Sitetools.
3. asciidoctor-maven-plugin: implement the interface and keep the injection
as a fallback (to be proposed there).
Related: the question to Maven core about propagating the mojo execution
scope to other threads, apache/maven#<MAVEN>.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
