This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-doxia-converter.git
commit 15c4804fc8a9254eb591a5a7f705d7f841923606 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Tue Nov 3 22:12:30 2026 +0000 Convert a shared source directory with documents of several formats --- .../org/apache/maven/doxia/DefaultConverter.java | 125 ++++++++++++++++++--- .../org/apache/maven/doxia/cli/CLIManager.java | 3 +- .../org/apache/maven/doxia/cli/ConverterCli.java | 11 +- .../maven/doxia/wrapper/InputFileWrapper.java | 8 +- src/site/markdown/usage.md.vm | 22 +++- .../java/org/apache/maven/doxia/ConverterTest.java | 64 +++++++++++ 6 files changed, 208 insertions(+), 25 deletions(-) diff --git a/src/main/java/org/apache/maven/doxia/DefaultConverter.java b/src/main/java/org/apache/maven/doxia/DefaultConverter.java index 0a33920..492c5a0 100644 --- a/src/main/java/org/apache/maven/doxia/DefaultConverter.java +++ b/src/main/java/org/apache/maven/doxia/DefaultConverter.java @@ -39,6 +39,7 @@ import java.nio.file.Path; import java.nio.file.StandardCopyOption; import java.util.ArrayList; import java.util.Arrays; +import java.util.Collections; import java.util.EnumSet; import java.util.HashMap; import java.util.LinkedHashMap; @@ -373,7 +374,11 @@ public class DefaultConverter implements Converter { outputRenameMap.clear(); if (input.getFile().isFile()) { - convert(input.getFile(), input.getEncoding(), input.getFormat(), output); + DoxiaFormat format = + input.getFormat() != null ? input.getFormat() : DoxiaFormat.autoDetectFormat(input.getFile()); + convert(input.getFile(), input.getEncoding(), format, output); + } else if (input.getFormat() == null) { + convertSharedSourceDirectory(input, output); } else { List<File> files; try { @@ -407,6 +412,108 @@ public class DefaultConverter implements Converter { } } + /** + * The file extensions that Doxia parser modules declare. In a shared source directory, such as + * <code>src/site/source</code>, Doxia Sitetools picks the parser by these extensions. + */ + static final Map<String, DoxiaFormat> SOURCE_EXTENSIONS; + + static { + Map<String, DoxiaFormat> extensions = new LinkedHashMap<>(); + extensions.put("apt", DoxiaFormat.APT); + extensions.put("fml", DoxiaFormat.FML); + extensions.put("xml", DoxiaFormat.XDOC); + extensions.put("xhtml", DoxiaFormat.XHTML); + extensions.put("md", DoxiaFormat.MARKDOWN); + extensions.put("markdown", DoxiaFormat.MARKDOWN); + SOURCE_EXTENSIONS = Collections.unmodifiableMap(extensions); + } + + /** + * Converts a directory that holds documents of several formats, the format of each picked by its extension as in + * {@link #SOURCE_EXTENSIONS}. Documents already in the output format are left alone, and so is an XML document + * whose root element does not match its format, such as a <code>site.xml</code>. Fails before converting anything + * if two documents would be written to the same output file. + */ + private void convertSharedSourceDirectory(InputFileWrapper input, OutputFileWrapper output) + throws ConverterException, UnsupportedFormatException { + List<File> files; + try { + files = FileUtils.getFiles( + input.getFile(), + getFileNamePatterns( + new ArrayList<>(SOURCE_EXTENSIONS.keySet()), !input.isExcludeVelocityTemplates()), + StringUtils.join(FileUtils.getDefaultExcludes(), ", ")); + } catch (IOException e) { + throw new ConverterException("IOException: " + e.getMessage(), e); + } + + Map<File, DoxiaFormat> formats = new LinkedHashMap<>(); + Map<File, File> outputs = new HashMap<>(); + for (File f : files) { + String name = f.getName(); + if (name.endsWith(VELOCITY_TEMPLATE_EXTENSION)) { + name = name.substring(0, name.length() - VELOCITY_TEMPLATE_EXTENSION.length()); + } + DoxiaFormat format = + SOURCE_EXTENSIONS.get(FileUtils.getExtension(name).toLowerCase(Locale.ENGLISH)); + if (format == output.getFormat()) { + LOGGER.debug("Skipping \"{}\", already in format {}", f, format); + continue; + } + if (format.isXml() + && !f.getName().endsWith(VELOCITY_TEMPLATE_EXTENSION) + && !format.firstElement.equals(getFirstTag(f))) { + LOGGER.warn("Skipping \"{}\", its root element is not <{}>", f, format.firstElement); + continue; + } + File relativeOutputDirectory = + new File(PathTool.getRelativeFilePath(input.getFile().getAbsolutePath(), f.getParent())); + File outputFile = new File( + new File(output.getFile(), relativeOutputDirectory.getPath()), + getOutputFileName(f, output.getFormat())); + File other = outputs.put(outputFile.getAbsoluteFile(), f); + if (other != null) { + throw new ConverterException("ConverterException: \"" + other + "\" and \"" + f + + "\" would both be converted to \"" + outputFile + "\""); + } + formats.put(f, format); + } + if (formats.isEmpty()) { + throw new ConverterException("ConverterException: No files to convert to " + output.getFormat() + + " found in directory " + input.getFile()); + } + for (Map.Entry<File, DoxiaFormat> entry : formats.entrySet()) { + File f = entry.getKey(); + File relativeOutputDirectory = + new File(PathTool.getRelativeFilePath(input.getFile().getAbsolutePath(), f.getParent())); + convert(f, input.getEncoding(), entry.getValue(), output, relativeOutputDirectory); + } + if (postProcess == PostProcess.NONE + && input.getFile().getAbsoluteFile().equals(output.getFile().getAbsoluteFile())) { + LOGGER.warn( + "The converted documents sit next to their sources in {}; remove the sources, or Doxia Sitetools" + + " reports each pair as a duplicate page", + input.getFile()); + } + } + + /** + * @param inputFile the input file, a Velocity template when its name ends with <code>.vm</code> + * @param outputFormat the output format + * @return the name of the output file: the input file name with the output format's extension + */ + static String getOutputFileName(File inputFile, DoxiaFormat outputFormat) { + String name = inputFile.getName(); + if (name.endsWith(VELOCITY_TEMPLATE_EXTENSION)) { + return FileUtils.removeExtension(name.substring(0, name.length() - VELOCITY_TEMPLATE_EXTENSION.length())) + + "." + + outputFormat.getExtension() + + VELOCITY_TEMPLATE_EXTENSION; + } + return FileUtils.removeExtension(name) + "." + outputFormat.getExtension(); + } + static String getFileNamePatterns(List<String> extensions, boolean includeVelocityTemplates) { StringJoiner patterns = new StringJoiner(","); for (String extension : extensions) { @@ -525,7 +632,7 @@ public class DefaultConverter implements Converter { /** * @param inputFile a not null existing file. * @param inputEncoding a not null supported encoding or {@link InputFileWrapper#AUTO_ENCODING} - * @param parserFormat a not null supported format or {@link InputFileWrapper#AUTO_FORMAT} + * @param parserFormat a not null supported format * @param output not null OutputFileWrapper object * @throws ConverterException if any * @throws UnsupportedFormatException if any @@ -576,19 +683,7 @@ public class DefaultConverter implements Converter { || relativeOutputDirectory != null) { // assume it is a directory outputDirectoryOrFile.mkdirs(); - final String outputFileName; - if (isVelocityTemplate) { - outputFileName = FileUtils.removeExtension(inputFile - .getName() - .substring(0, inputFile.getName().length() - VELOCITY_TEMPLATE_EXTENSION.length())) - + "." - + output.getFormat().getExtension() - + VELOCITY_TEMPLATE_EXTENSION; - } else { - outputFileName = FileUtils.removeExtension(inputFile.getName()) + "." - + output.getFormat().getExtension(); - } - outputFile = new File(outputDirectoryOrFile, outputFileName); + outputFile = new File(outputDirectoryOrFile, getOutputFileName(inputFile, output.getFormat())); } else { outputDirectoryOrFile.getParentFile().mkdirs(); outputFile = output.getFile(); diff --git a/src/main/java/org/apache/maven/doxia/cli/CLIManager.java b/src/main/java/org/apache/maven/doxia/cli/CLIManager.java index 9e94efa..ccdbdaa 100644 --- a/src/main/java/org/apache/maven/doxia/cli/CLIManager.java +++ b/src/main/java/org/apache/maven/doxia/cli/CLIManager.java @@ -113,7 +113,8 @@ class CLIManager { .hasArg() .build()); OPTIONS.addOption(Option.builder(FROM) - .desc("From format. If not specified, try to autodetect it (only works if input is a single file).") + .desc("From format. If not specified, autodetect it: for a directory, per file by extension, such as" + + " .md, .apt, .xml (xdoc), .xhtml or .fml, skipping files already in the target format.") .hasArg() .build()); OPTIONS.addOption(Option.builder(TO).desc("To format.").hasArg().build()); diff --git a/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java b/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java index ba82212..f46533a 100644 --- a/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java +++ b/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java @@ -123,9 +123,14 @@ public class ConverterCli { final DefaultConverter.DoxiaFormat parserFormat; if (CLIManager.AUTO_FORMAT.equalsIgnoreCase(sourceFormat)) { File inputFile = new File(commandLine.getOptionValue(CLIManager.IN)); - parserFormat = DefaultConverter.DoxiaFormat.autoDetectFormat(inputFile); - if (debug) { - System.out.println("Auto detected input format: " + parserFormat); + if (inputFile.isDirectory()) { + // detected per file, by extension + parserFormat = null; + } else { + parserFormat = DefaultConverter.DoxiaFormat.autoDetectFormat(inputFile); + if (debug) { + System.out.println("Auto detected input format: " + parserFormat); + } } } else { parserFormat = DefaultConverter.DoxiaFormat.valueOf(sourceFormat.toUpperCase()); diff --git a/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java b/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java index cc9b80a..56912a4 100644 --- a/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java +++ b/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java @@ -40,7 +40,7 @@ public class InputFileWrapper extends AbstractFileWrapper { * Private constructor. * * @param absolutePath not null - * @param format not null + * @param format the format, or null to detect it per file * @param charsetName could be null * @param excludeVelocityTemplates {@code true} to not consider velocity templates (ending with .vm) (only relevant when absolutePath is a directory) * @throws UnsupportedEncodingException if the encoding is unsupported. @@ -63,7 +63,7 @@ public class InputFileWrapper extends AbstractFileWrapper { /** * @param absolutePath for a file or a directory not null. - * @param format not null + * @param format the format, or null to detect it per file * @return a type safe input reader * @throws UnsupportedEncodingException if the encoding is unsupported. * @throws FileNotFoundException if the file for absolutePath is not found. @@ -76,7 +76,7 @@ public class InputFileWrapper extends AbstractFileWrapper { /** * @param absolutePath for a wanted file or a wanted directory, not null. - * @param format not null + * @param format the format, or null to detect it per file * @param charsetName could be null * @return a type safe input reader * @throws UnsupportedEncodingException if the encoding is unsupported. @@ -89,7 +89,7 @@ public class InputFileWrapper extends AbstractFileWrapper { /** * @param absolutePath for a wanted file or a wanted directory, not null. - * @param format not null + * @param format the format, or null to detect it per file * @param charsetName could be null * @param excludeVelocityTemplates {@code true} to not consider velocity templates (ending with .vm) * @return a type safe input reader diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index e0bd346..a2c46fb 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -42,7 +42,8 @@ usage: doxia-converter [-e] [-f] [-from <arg>] [-h] [-in <arg>] [-inEncoding <ar Options: -e,--errors Produce execution error messages. -f,--format Format the output (actually only xml based outputs) to be human readable. - -from <arg> From format. If not specified, try to autodetect it. + -from <arg> From format. If not specified, autodetect it: for a directory, per file by extension, such as .md, + .apt, .xml (xdoc), .xhtml or .fml, skipping files already in the target format. -h,--help Display help information. -in,--input <arg> Input file or directory. -inEncoding <arg> Input file encoding. If not specified, try to autodetect it (only works if input is a single file) @@ -76,7 +77,24 @@ Command Line Execution -to markdown ``` -**Note**: The `from` parameter can be empty. In that case, Doxia converter tries to autodetect the `from` input from the `in` file parameter, this only works when the input is a file (and not a directory). +**Note**: The `from` parameter can be empty. In that case, Doxia converter autodetects the format of the `in` file, or of each file in the `in` directory. + +Shared Source Directory +----------------------- + +Doxia Sitetools can read documents of any format from one directory, `src/site/source`, where the file extension picks the parser. Without `-from`, the converter reads such a directory the same way: `.apt` is APT, `.md` and `.markdown` are Markdown, `.xml` is XDoc, `.xhtml` is XHTML and `.fml` is FML, each optionally followed by `.vm`. Files already in the target format are left alone, and so is an `.xml` file whose root element is not `<document>`. + +To convert every remaining document to Markdown in place, keeping the history in Git: + +``` +# java -jar target/doxia-converter-${project.version}-shaded.jar \ + -in src/site/source \ + -out src/site/source \ + -to markdown \ + -gitMvInputToOutput +``` + +Use `-removeIn` instead outside Git. Without either, each source stays next to its converted document, and Doxia Sitetools reports the pair as a duplicate page. The conversion stops before writing anything if two documents, such as `usage.apt` and `usage.xml`, would produce the same output file. Java Usage ---------- diff --git a/src/test/java/org/apache/maven/doxia/ConverterTest.java b/src/test/java/org/apache/maven/doxia/ConverterTest.java index 61354a1..11404c6 100644 --- a/src/test/java/org/apache/maven/doxia/ConverterTest.java +++ b/src/test/java/org/apache/maven/doxia/ConverterTest.java @@ -48,7 +48,9 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertLinesMatch; +import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; @@ -484,4 +486,66 @@ class ConverterTest extends InjectedTest { assertTrue(markdown.contains("Text after the object."), "text after object missing from:\n" + markdown); } } + + /** + * Converts a shared source directory, such as <code>src/site/source</code>, in place: every document not yet in + * Markdown is converted next to its source, picking the parser by its extension. + */ + @Test + void sharedSourceDirectoryInPlace() throws Exception { + File dir = new File(getBasedir(), "target/unit/shared/source"); + FileUtils.deleteDirectory(dir); + String markdown = "# Index\n\nAlready Markdown.\n"; + write(new File(dir, "index.md"), markdown); + write(new File(dir, "guide/usage.apt"), "Usage\n\n* APT\n\n Text.\n"); + write( + new File(dir, "about.xml"), + "<document><body><section name=\"About\"><p>XDoc</p></section></body></document>"); + write( + new File(dir, "faq.fml"), + "<faqs title=\"FAQ\"><part id=\"p\"><faq id=\"q\"><question>Q?</question>" + + "<answer><p>A.</p></answer></faq></part></faqs>"); + write(new File(dir, "notes.apt.vm"), "Notes\n\n* Version\n\n ${project.version}\n"); + write(new File(dir, "site.xml"), "<site><body/></site>"); + + converter.convert( + InputFileWrapper.valueOf(dir.getPath(), null), + OutputFileWrapper.valueOf(dir.getPath(), DoxiaFormat.MARKDOWN, StandardCharsets.UTF_8.name())); + + assertTrue(new File(dir, "guide/usage.md").isFile()); + assertTrue(readFile(new File(dir, "about.md")).contains("XDoc")); + assertTrue(readFile(new File(dir, "faq.md")).contains("Q?")); + assertTrue(readFile(new File(dir, "notes.md.vm")).contains("${project.version}")); + assertEquals(markdown, readFile(new File(dir, "index.md"))); + assertFalse(new File(dir, "site.md").exists()); + + FileUtils.deleteDirectory(dir); + } + + @Test + void sharedSourceDirectoryRejectsTwoSourcesForOneOutput() throws Exception { + File dir = new File(getBasedir(), "target/unit/shared-duplicate/source"); + FileUtils.deleteDirectory(dir); + write(new File(dir, "usage.apt"), "Usage\n\n* APT\n\n Text.\n"); + write(new File(dir, "usage.xml"), "<document><body><section name=\"Usage\"/></body></document>"); + + ConverterException e = assertThrows( + ConverterException.class, + () -> converter.convert( + InputFileWrapper.valueOf(dir.getPath(), null), + OutputFileWrapper.valueOf(dir.getPath(), DoxiaFormat.MARKDOWN, StandardCharsets.UTF_8.name()))); + assertTrue(e.getMessage().contains("usage.md"), e.getMessage()); + assertFalse(new File(dir, "usage.md").exists()); + + FileUtils.deleteDirectory(dir); + } + + private static void write(File file, String content) throws IOException { + file.getParentFile().mkdirs(); + Files.write(file.toPath(), content.getBytes(StandardCharsets.UTF_8)); + } + + private static String readFile(File file) throws IOException { + return new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8); + } }
