You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by mi...@apache.org on 2023/11/18 08:59:11 UTC
(maven-doxia-sitetools) 01/01: [DOXIASITETOOLS-319] Improve DocumentRenderer interface/DocumentRenderingContext class API
This is an automated email from the ASF dual-hosted git repository.
michaelo pushed a commit to branch DOXIASITETOOLS-319
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
commit f86516bc8c7bc4e50788cc3f01b172c9d85741c7
Author: Michael Osipov <mi...@apache.org>
AuthorDate: Tue Nov 14 21:17:01 2023 +0100
[DOXIASITETOOLS-319] Improve DocumentRenderer interface/DocumentRenderingContext class API
This closes #118
---
.../doxia/siterenderer/DefaultSiteRenderer.java | 15 +++--
.../maven/doxia/siterenderer/DocumentRenderer.java | 15 ++++-
.../siterenderer/DocumentRenderingContext.java | 46 ++++++++++-----
doxia-site-renderer/src/site/apt/index.apt.vm | 10 +++-
.../siterenderer/DefaultSiteRendererTest.java | 6 +-
.../doxia/siterenderer/RenderingContextTest.java | 38 ++++++-------
.../siterenderer/velocity-toolmanager.expected.txt | 66 +++++++++++-----------
.../src/test/resources/site/apt/interpolation.apt | 2 +-
8 files changed, 119 insertions(+), 79 deletions(-)
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
index 8ac4c14..9c532ac 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
@@ -395,10 +395,10 @@ public class DefaultSiteRenderer implements Renderer {
siteContext.getProcessedContentOutput().mkdirs();
}
- String inputName = docRenderingContext.getInputName();
+ String inputPath = docRenderingContext.getInputName();
// Remove .vm suffix
File outputFile =
- new File(siteContext.getProcessedContentOutput(), inputName.substring(0, inputName.length() - 3));
+ new File(siteContext.getProcessedContentOutput(), inputPath.substring(0, inputPath.length() - 3));
File outputParent = outputFile.getParentFile();
if (!outputParent.exists()) {
@@ -475,10 +475,15 @@ public class DefaultSiteRenderer implements Renderer {
context.put("relativePath", docRenderingContext.getRelativePath());
- String currentFileName = docRenderingContext.getOutputName();
- context.put("currentFileName", currentFileName);
+ String currentFilePath = docRenderingContext.getOutputName();
+ context.put("currentFilePath", currentFilePath);
+ // TODO Deprecated -- will be removed!
+ context.put("currentFileName", currentFilePath);
- context.put("alignedFileName", PathTool.calculateLink(currentFileName, docRenderingContext.getRelativePath()));
+ String alignedFilePath = PathTool.calculateLink(currentFilePath, docRenderingContext.getRelativePath());
+ context.put("alignedFilePath", alignedFilePath);
+ // TODO Deprecated -- will be removed!
+ context.put("alignedFileName", alignedFilePath);
context.put("site", siteRenderingContext.getSiteModel());
// TODO Deprecated -- will be removed!
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderer.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderer.java
index f208161..e300b82 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderer.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderer.java
@@ -41,10 +41,23 @@ public interface DocumentRenderer {
throws IOException, RendererException;
/**
- * The name of the output document.
+ * The output path of the document.
+ * <p>
+ * Note: This method won't be {@code default} anymore when {@link #getOutputName()} is removed.
+ * You are advised to implement it as soon as possible.
*
+ * @since 2.0.0
* @return the name of the output document.
*/
+ default String getOutputPath() {
+ return getOutputName();
+ }
+
+ /**
+ * @deprecated Method name does not properly reflect its purpose. Implement and use
+ * {@link #getOutputPath()} instead.
+ */
+ @Deprecated
String getOutputName();
/**
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.java
index ac27bf8..b176c83 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.java
@@ -36,9 +36,9 @@ public class DocumentRenderingContext {
private final String basedirRelativePath;
- private final String inputName;
+ private final String inputPath;
- private final String outputName;
+ private final String outputPath;
private final String parserId;
@@ -58,7 +58,7 @@ public class DocumentRenderingContext {
* </p>
*
* @param basedir the pseudo-source base directory.
- * @param document the pseudo-source document name: will be used to compute output name (same name with extension
+ * @param document the pseudo-source document path: will be used to compute output path (same path with extension
* replaced with <code>.html</code>).
* @param generator the generator (in general a reporting goal: <code>groupId:artifactId:version:goal</code>)
* @since 1.8
@@ -84,7 +84,7 @@ public class DocumentRenderingContext {
*
* @param basedir the source base directory (not null, pseudo value when not a Doxia source).
* @param basedirRelativePath the relative path from root (null if not Doxia source)
- * @param document the source document name.
+ * @param document the source document path.
* @param parserId the Doxia module parser id associated to this document, may be null if document not rendered from
* a Doxia source.
* @param extension the source document filename extension, may be null if document not rendered from
@@ -108,7 +108,7 @@ public class DocumentRenderingContext {
this.attributes = new HashMap<>();
document = document.replace('\\', '/');
- this.inputName = document;
+ this.inputPath = document;
if (extension != null && !extension.isEmpty()) {
this.basedirRelativePath = basedirRelativePath.replace('\\', '/');
@@ -122,16 +122,16 @@ public class DocumentRenderingContext {
if (DefaultSiteRenderer.endsWithIgnoreCase(document, ".vm")) {
document = document.substring(0, document.length() - 3);
}
- String fileNameWithoutExt = document.substring(0, document.length() - extension.length() - 1);
- this.outputName = fileNameWithoutExt + ".html";
+ String filePathWithoutExt = document.substring(0, document.length() - extension.length() - 1);
+ this.outputPath = filePathWithoutExt + ".html";
} else {
// document does not come from a Doxia source but direct Sink API, so no file extension to strip
this.basedirRelativePath = null;
this.editable = false;
- this.outputName = document + ".html";
+ this.outputPath = document + ".html";
}
- this.relativePath = PathTool.getRelativePath(basedir.getPath(), new File(basedir, inputName).getPath())
+ this.relativePath = PathTool.getRelativePath(basedir.getPath(), new File(basedir, inputPath).getPath())
.replace('\\', '/');
}
@@ -145,22 +145,38 @@ public class DocumentRenderingContext {
}
/**
- * <p>Getter for the field <code>inputName</code>.</p>
+ * <p>Getter for the field <code>inputPath</code>.</p>
*
* @return a {@link java.lang.String} object.
*/
+ public String getInputPath() {
+ return inputPath;
+ }
+
+ /**
+ * @deprecated Method name does not properly reflect its purpose. Use {@link #getInputPath()} instead.
+ */
+ @Deprecated
public String getInputName() {
- return inputName;
+ return getInputPath();
}
/**
- * Get html output name, relative to site root.
+ * Get html output path, relative to site root.
*
- * @return html output name
+ * @return html output path
* @see PathTool#getRelativePath(String)
*/
+ public String getOutputPath() {
+ return outputPath;
+ }
+
+ /**
+ * @deprecated Method name does not properly reflect its purpose. Use {@link #getOutputPath()} instead.
+ */
+ @Deprecated
public String getOutputName() {
- return outputName;
+ return getOutputPath();
}
/**
@@ -257,7 +273,7 @@ public class DocumentRenderingContext {
* @since 1.8
*/
public String getDoxiaSourcePath() {
- return isDoxiaSource() ? (basedirRelativePath + '/' + inputName) : null;
+ return isDoxiaSource() ? (basedirRelativePath + '/' + inputPath) : null;
}
/**
diff --git a/doxia-site-renderer/src/site/apt/index.apt.vm b/doxia-site-renderer/src/site/apt/index.apt.vm
index 8309306..e9d9d5a 100644
--- a/doxia-site-renderer/src/site/apt/index.apt.vm
+++ b/doxia-site-renderer/src/site/apt/index.apt.vm
@@ -57,11 +57,15 @@ Doxia Sitetools - Site Renderer
*---------------------------------+----------------------+-------------------------------+
|| Variable || Type || Description ||
*---------------------------------+----------------------+-------------------------------+
-| <<<alignedFileName>>> | <<<String>>> | The file name of the (HTML) document being rendered, relative to the document being rendered. |
+| <<<alignedFileName>>> | <<<String>>> | <<Deprecated>>: use <<<alignedFilePath>>>. |
*---------------------------------+----------------------+-------------------------------+
-| <<<decoration>>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<<SiteModel>>>}} | <<Deprecated>>}: use <<<site>>>. |
+| <<<alignedFilePath>>> | <<<String>>> | The file path of the (HTML) document being rendered, relative to the document being rendered. |
*---------------------------------+----------------------+-------------------------------+
-| <<<currentFileName>>> | <<<String>>> | The file name of the (HTML) document being rendered, relative to the site root. |
+| <<<decoration>>> | {{{../doxia-site-model/apidocs/org/apache/maven/doxia/site/SiteModel.html}<<<SiteModel>>>}} | <<Deprecated>>: use <<<site>>>. |
+*---------------------------------+----------------------+-------------------------------+
+| <<<currentFileName>>> | <<<String>>> | <<Deprecated>>: use <<<currentFilePath>>>. |
+*---------------------------------+----------------------+-------------------------------+
+| <<<currentFilePath>>> | <<<String>>> | The file path of the (HTML) document being rendered, relative to the site root. |
*---------------------------------+----------------------+-------------------------------+
| <<<doxiaSiteRendererVersion>>> | <<<String>>> | The version of the Doxia Site Renderer in use. |
*---------------------------------+----------------------+-------------------------------+
diff --git a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DefaultSiteRendererTest.java b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DefaultSiteRendererTest.java
index 8a42399..f9c1a0b 100644
--- a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DefaultSiteRendererTest.java
+++ b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/DefaultSiteRendererTest.java
@@ -138,7 +138,7 @@ public class DefaultSiteRendererTest {
@Test
public void testRenderExceptionMessageWhenLineNumberIsNotAvailable() throws Exception {
final File testBasedir = getTestFile("src/test/resources/site/xdoc");
- final String testDocumentName = "head.xml";
+ final String testDocument = "head.xml";
final String exceptionMessage = "parse error occurred";
Doxia doxiaInstance = container.lookup(Doxia.class);
@@ -150,7 +150,7 @@ public class DefaultSiteRendererTest {
ReflectionUtils.setVariableValueInObject(siteRenderer, "doxia", doxiaSpy);
DocumentRenderingContext docRenderingContext =
- new DocumentRenderingContext(testBasedir, "", testDocumentName, "xdoc", "", false);
+ new DocumentRenderingContext(testBasedir, "", testDocument, "xdoc", "", false);
try {
siteRenderer.renderDocument(null, docRenderingContext, new SiteRenderingContext());
@@ -158,7 +158,7 @@ public class DefaultSiteRendererTest {
} catch (RendererException e) {
assertEquals(
String.format(
- "Error parsing '%s%s%s'", testBasedir.getAbsolutePath(), File.separator, testDocumentName),
+ "Error parsing '%s%s%s'", testBasedir.getAbsolutePath(), File.separator, testDocument),
e.getMessage());
}
}
diff --git a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/RenderingContextTest.java b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/RenderingContextTest.java
index 2a902c4..93d5fd8 100644
--- a/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/RenderingContextTest.java
+++ b/doxia-site-renderer/src/test/java/org/apache/maven/doxia/siterenderer/RenderingContextTest.java
@@ -39,38 +39,38 @@ public class RenderingContextTest {
* @throws java.lang.Exception if any.
*/
@Test
- public void testFileNameWithDot() throws Exception {
+ public void testFilePathWithDot() throws Exception {
File baseDir = new File(getBasedir() + File.separatorChar + "test" + File.separatorChar + "resources");
- String docName = "file.with.dot.in.name.xml";
+ String document = "file.with.dot.in.name.xml";
DocumentRenderingContext docRenderingContext =
- new DocumentRenderingContext(baseDir, "test", docName, "", "xml", false);
- assertEquals("file.with.dot.in.name.html", docRenderingContext.getOutputName());
+ new DocumentRenderingContext(baseDir, "test", document, "", "xml", false);
+ assertEquals("file.with.dot.in.name.html", docRenderingContext.getOutputPath());
assertEquals(".", docRenderingContext.getRelativePath());
- docName = "file.with.dot.in.name";
- docRenderingContext = new DocumentRenderingContext(baseDir, docName, "generator"); // not Doxia source
- assertEquals("file.with.dot.in.name.html", docRenderingContext.getOutputName());
+ document = "file.with.dot.in.name";
+ docRenderingContext = new DocumentRenderingContext(baseDir, document, "generator"); // not Doxia source
+ assertEquals("file.with.dot.in.name.html", docRenderingContext.getOutputPath());
assertEquals(".", docRenderingContext.getRelativePath());
- docName = "index.xml.vm";
- docRenderingContext = new DocumentRenderingContext(baseDir, "test", docName, "", "xml", false);
- assertEquals("index.html", docRenderingContext.getOutputName());
+ document = "index.xml.vm";
+ docRenderingContext = new DocumentRenderingContext(baseDir, "test", document, "", "xml", false);
+ assertEquals("index.html", docRenderingContext.getOutputPath());
assertEquals(".", docRenderingContext.getRelativePath());
- docName = "download.apt.vm";
- docRenderingContext = new DocumentRenderingContext(baseDir, "test", docName, "", "apt", false);
- assertEquals("download.html", docRenderingContext.getOutputName());
+ document = "download.apt.vm";
+ docRenderingContext = new DocumentRenderingContext(baseDir, "test", document, "", "apt", false);
+ assertEquals("download.html", docRenderingContext.getOutputPath());
assertEquals(".", docRenderingContext.getRelativePath());
- docName = "path/file.apt";
- docRenderingContext = new DocumentRenderingContext(baseDir, "test", docName, "", "apt", false);
- assertEquals("path/file.html", docRenderingContext.getOutputName());
+ document = "path/file.apt";
+ docRenderingContext = new DocumentRenderingContext(baseDir, "test", document, "", "apt", false);
+ assertEquals("path/file.html", docRenderingContext.getOutputPath());
assertEquals("..", docRenderingContext.getRelativePath());
- docName = "path/file";
- docRenderingContext = new DocumentRenderingContext(baseDir, docName, "generator"); // not Doxia source
- assertEquals("path/file.html", docRenderingContext.getOutputName());
+ document = "path/file";
+ docRenderingContext = new DocumentRenderingContext(baseDir, document, "generator"); // not Doxia source
+ assertEquals("path/file.html", docRenderingContext.getOutputPath());
assertEquals("..", docRenderingContext.getRelativePath());
}
}
diff --git a/doxia-site-renderer/src/test/resources/org/apache/maven/doxia/siterenderer/velocity-toolmanager.expected.txt b/doxia-site-renderer/src/test/resources/org/apache/maven/doxia/siterenderer/velocity-toolmanager.expected.txt
index 98380c1..e67391d 100644
--- a/doxia-site-renderer/src/test/resources/org/apache/maven/doxia/siterenderer/velocity-toolmanager.expected.txt
+++ b/doxia-site-renderer/src/test/resources/org/apache/maven/doxia/siterenderer/velocity-toolmanager.expected.txt
@@ -5,35 +5,37 @@ We have the following keys in the context:
1. PathTool
2. StringUtils
3. alignedFileName
- 4. alternator
- 5. authors
- 6. bodyContent
- 7. class
- 8. context
- 9. convert
- 10. currentFileName
- 11. date
- 12. decoration
- 13. display
- 14. docRenderingContext
- 15. documentDate
- 16. doxiaSiteRendererVersion
- 17. esc
- 18. field
- 19. headContent
- 20. link
- 21. locale
- 22. loop
- 23. math
- 24. number
- 25. plexus
- 26. publishDate
- 27. relativePath
- 28. render
- 29. shortTitle
- 30. site
- 31. sorter
- 32. supportedLocales
- 33. text
- 34. title
- 35. xml
+ 4. alignedFilePath
+ 5. alternator
+ 6. authors
+ 7. bodyContent
+ 8. class
+ 9. context
+ 10. convert
+ 11. currentFileName
+ 12. currentFilePath
+ 13. date
+ 14. decoration
+ 15. display
+ 16. docRenderingContext
+ 17. documentDate
+ 18. doxiaSiteRendererVersion
+ 19. esc
+ 20. field
+ 21. headContent
+ 22. link
+ 23. locale
+ 24. loop
+ 25. math
+ 26. number
+ 27. plexus
+ 28. publishDate
+ 29. relativePath
+ 30. render
+ 31. shortTitle
+ 32. site
+ 33. sorter
+ 34. supportedLocales
+ 35. text
+ 36. title
+ 37. xml
diff --git a/doxia-site-renderer/src/test/resources/site/apt/interpolation.apt b/doxia-site-renderer/src/test/resources/site/apt/interpolation.apt
index 1c938bb..95916ce 100644
--- a/doxia-site-renderer/src/test/resources/site/apt/interpolation.apt
+++ b/doxia-site-renderer/src/test/resources/site/apt/interpolation.apt
@@ -29,5 +29,5 @@
Things you can do with Velocity
* project = ${project.name} ${project.version}
- * $currentFileName
+ * $currentFilePath