Allow to set an alternative source directory (for editing)

Always check if a file is existing before returning true for isEditable
and non-null for getDoxiaSourcePath()/getDoxiaSourcePath(String)

This closes #277

Author: kwin

doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java

@@ -198,12 +198,11 @@ public Map<String, DocumentRenderer> locateDocumentFiles(SiteRenderingContext si
 
                     addModuleFiles(
                             siteRenderingContext.getRootDirectory(),
+                            siteDirectory,
                             moduleBasedir,
                             module,
                             excludes,
-                            files,
-                            siteDirectory.isEditable(),
-                            siteDirectory.isSkipDuplicates());
+                            files);
                 }
             }
         }
@@ -228,32 +227,27 @@ private List<String> filterExtensionIgnoreCase(List<String> fileNames, String ex
      * Populates the files map with {@link DocumentRenderer}s per output name in parameter {@code files} for all files in the moduleBasedir matching the module extensions,
      * taking care of duplicates if needed.
      *
-     * @param rootDir
+     * @param siteRootDirectory
+     * @param siteDirectory
      * @param moduleBasedir
      * @param module
      * @param excludes
      * @param files
-     * @param editable
-     * @param skipDuplicates
      * @throws IOException
      * @throws RendererException
      */
     private void addModuleFiles(
-            File rootDir,
+            File siteRootDirectory,
+            SiteDirectory siteDirectory,
             File moduleBasedir,
             ParserModule module,
             String excludes,
-            Map<String, DocumentRenderer> files,
-            boolean editable,
-            boolean skipDuplicates)
+            Map<String, DocumentRenderer> files)
             throws IOException, RendererException {
         if (!moduleBasedir.exists() || ArrayUtils.isEmpty(module.getExtensions())) {
             return;
         }
 
-        String moduleRelativePath =
-                PathTool.getRelativeFilePath(rootDir.getAbsolutePath(), moduleBasedir.getAbsolutePath());
-
         List<String> allFiles = FileUtils.getFileNames(moduleBasedir, "**/*", excludes, false);
 
         for (String extension : module.getExtensions()) {
@@ -268,14 +262,20 @@ private void addModuleFiles(
 
             for (String doc : docs) {
                 DocumentRenderingContext docRenderingContext = new DocumentRenderingContext(
-                        moduleBasedir, moduleRelativePath, doc, module.getParserId(), extension, editable);
+                        moduleBasedir,
+                        doc,
+                        module.getParserId(),
+                        extension,
+                        siteRootDirectory,
+                        siteDirectory.getPath(),
+                        siteDirectory.getEditableSourceDirectories());
 
                 // TODO: DOXIA-111: we need a general filter here that knows how to alter the context
                 if (endsWithIgnoreCase(doc, ".vm")) {
                     docRenderingContext.setAttribute("velocity", "true");
                 }
 
-                if (!checkForDuplicate(docRenderingContext, files, skipDuplicates)) {
+                if (!checkForDuplicate(docRenderingContext, files, siteDirectory.isSkipDuplicates())) {
                     String key = docRenderingContext.getOutputName();
                     files.put(key, new DoxiaDocumentRenderer(docRenderingContext));
                 }

doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DocumentRenderingContext.java

@@ -19,8 +19,11 @@
 package org.apache.maven.doxia.siterenderer;
 
 import java.io.File;
+import java.util.Collection;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Objects;
 
 import org.codehaus.plexus.util.PathTool;
 
@@ -32,26 +35,59 @@
  * @since 1.5 (was since 1.1 in o.a.m.d.sink.render)
  */
 public class DocumentRenderingContext {
-    private final File basedir;
 
-    private final String basedirRelativePath;
+    /** absolute path to the source base directory (not null, pseudo value when not a Doxia source), this is parser format specific. Must start with {@link #siteRootDirectory}. */
+    private final File basedir;
 
+    /** {@link #basedir} relative path to the document's source including {@link #extension}. May be {@code null} if not rendered from a Doxia source */
     private final String inputPath;
 
+    /** same as {@link #inputPath} but with extension replaced with {@code .html}, this is parser format specific */
     private final String outputPath;
 
+    /** the Doxia module parser id associated to this document, may be null if document not rendered from a Doxia source. */
     private final String parserId;
 
-    private final String relativePath;
-
+    /** the source document filename extension, may be null if document not rendered from a Doxia source. */
     private final String extension;
 
     private Map<String, String> attributes;
 
-    private final boolean editable;
+    /**
+     * The absolute paths of directories which may contain the original editable source.
+     * If empty document is not editable.
+     */
+    private final Collection<File> sourceDirectories;
 
+    /** The project's build directory, may be {@code null} rendered from a Doxia source) */
+    private final File rootDirectory;
+
+    /** The site's root directory (never null), must be within below {@link #rootDirectory}, may be {@code null} rendered from a Doxia source */
+    private final File siteRootDirectory;
+
+    /** optional descriptive text of the plugin which generated the output (usually Maven coordinates). Only set when document is not based on a Doxia source. */
     private final String generator;
 
+    static File stripSuffixFromPath(File file, String suffix) {
+        File relevantFile = file;
+        if (suffix == null || suffix.isEmpty()) {
+            return relevantFile;
+        }
+        File currentSuffixPart = new File(suffix);
+        // compare elements from end, suffix should be a suffix of file
+        do {
+            if (currentSuffixPart.getName().equals(relevantFile.getName())) {
+                relevantFile = relevantFile.getParentFile();
+                if (relevantFile == null) {
+                    throw new IllegalArgumentException("Suffix " + suffix + " has more elements than file " + file);
+                }
+            } else {
+                throw new IllegalArgumentException("Suffix " + suffix + " is not a suffix of file " + file);
+            }
+        } while ((currentSuffixPart = currentSuffixPart.getParentFile()) != null);
+        return relevantFile;
+    }
+
     /**
      * <p>
      * Constructor for rendering context when document is not rendered from a Doxia markup source.
@@ -64,9 +100,10 @@ public class DocumentRenderingContext {
      * @since 1.8
      */
     public DocumentRenderingContext(File basedir, String document, String generator) {
-        this(basedir, null, document, null, null, false, generator);
+        this(basedir, document, null, null, null, null, Collections.emptySet(), generator);
     }
 
+    @Deprecated
     public DocumentRenderingContext(
             File basedir,
             String basedirRelativePath,
@@ -77,13 +114,36 @@ public DocumentRenderingContext(
         this(basedir, basedirRelativePath, document, parserId, extension, editable, null);
     }
 
+    /**
+     * <p>
+     * Constructor for rendering context when document is a Doxia markup source.
+     * </p>
+     * @param basedir
+     * @param document
+     * @param parserId
+     * @param extension
+     * @param rootDirectory
+     * @param sourceDirectories
+     * @since 2.1
+     */
+    public DocumentRenderingContext(
+            File basedir,
+            String document,
+            String parserId,
+            String extension,
+            File rootDirectory,
+            File siteRootDirectory,
+            Collection<File> sourceDirectories) {
+        this(basedir, document, parserId, extension, rootDirectory, siteRootDirectory, sourceDirectories, null);
+    }
+
     /**
      * <p>
      * Constructor for document rendering context.
      * </p>
      *
      * @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 basedirRelativePath the relative path from project root (null if not Doxia source)
      * @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.
@@ -92,7 +152,9 @@ public DocumentRenderingContext(
      * @param editable is the document editable as source, i.e. not generated?
      * @param generator the generator (in general a reporting goal: <code>groupId:artifactId:version:goal</code>)
      * @since 1.8
+     * @deprecated Use {@link #DocumentRenderingContext(File, String, String, String, File, Collection, String)} instead.
      */
+    @Deprecated
     public DocumentRenderingContext(
             File basedir,
             String basedirRelativePath,
@@ -101,6 +163,48 @@ public DocumentRenderingContext(
             String extension,
             boolean editable,
             String generator) {
+        this(
+                basedir,
+                document,
+                parserId,
+                extension,
+                stripSuffixFromPath(basedir, basedirRelativePath),
+                // assume that site root is the parent of basedir (i.e. module specific source directory is directly
+                // below site root)
+                basedir.getParentFile(),
+                editable ? Collections.singleton(basedir) : Collections.emptySet(),
+                generator);
+    }
+
+    /**
+     * <p>
+     * Constructor for document rendering context.
+     * </p>
+     *
+     * @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 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
+     *            a Doxia source.
+     * @param rootDirectory the absolute project's root directory (not null), usually {@code project.basedir}, must be an ancestor of {@code siteRootDirectory}
+     * @param siteRootDirectory the absolute site's root directory (not null), must start with {@code rootDirectory}, often ends with {@code /src/site}
+     * @param sourceDirectories the absolute paths of directories which may contain the original editable source.
+     * @param editable is the document editable as source, i.e. not generated?
+     * @param generator the generator (in general a reporting goal: <code>groupId:artifactId:version:goal</code>)
+     * @since 2.1
+     */
+    @SuppressWarnings("checkstyle:parameternumber")
+    public DocumentRenderingContext(
+            File basedir,
+            String document,
+            String parserId,
+            String extension,
+            File rootDirectory,
+            File siteRootDirectory,
+            Collection<File> sourceDirectories,
+            String generator) {
         this.basedir = basedir;
         this.parserId = parserId;
         this.extension = extension;
@@ -110,10 +214,23 @@ public DocumentRenderingContext(
         document = document.replace('\\', '/');
         this.inputPath = document;
 
+        if (rootDirectory == null) {
+            if (siteRootDirectory != null) {
+                throw new IllegalArgumentException("Root directory must not be null when site root directory is set");
+            }
+        } else {
+            Objects.requireNonNull(
+                    siteRootDirectory, "Site root directory must not be null when root directory is set");
+            if (!siteRootDirectory.getPath().startsWith(rootDirectory.getPath())) {
+                throw new IllegalArgumentException("Site root directory " + siteRootDirectory
+                        + " must start with root directory " + rootDirectory);
+            }
+        }
+        this.rootDirectory = rootDirectory;
+        this.siteRootDirectory = siteRootDirectory;
         if (extension != null && !extension.isEmpty()) {
-            this.basedirRelativePath = basedirRelativePath.replace('\\', '/');
             // document comes from a Doxia source: see DoxiaDocumentRenderer
-            this.editable = editable;
+            this.sourceDirectories = sourceDirectories;
 
             // here we know the parserId and extension, we can play with this to get output name from document:
             // - index.xml -> index.html
@@ -126,13 +243,9 @@ public DocumentRenderingContext(
             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.sourceDirectories = Collections.emptySet();
             this.outputPath = document + ".html";
         }
-
-        this.relativePath = PathTool.getRelativePath(basedir.getPath(), new File(basedir, inputPath).getPath())
-                .replace('\\', '/');
     }
 
     /**
@@ -189,12 +302,13 @@ public String getParserId() {
     }
 
     /**
-     * Get the relative path to site root.
+     * Get the relative path of the parent folder to site root.
      *
      * @return the relative path to site root
      */
     public String getRelativePath() {
-        return relativePath;
+        return PathTool.getRelativePath(basedir.getPath(), new File(basedir, inputPath).getPath())
+                .replace('\\', '/');
     }
 
     /**
@@ -233,7 +347,7 @@ public String getExtension() {
      * @since 1.8
      */
     public boolean isEditable() {
-        return editable;
+        return getDoxiaSourcePath() != null;
     }
 
     /**
@@ -257,27 +371,54 @@ public String getGenerator() {
     }
 
     /**
-     * Get the relative path of basedir (when a Doxia source)
+     * Get the project root relative path of basedir (when a Doxia source). For example {@code src/site/markdown}.
      *
      * @return the relative path of basedir when a Doxia source, or <code>null</code> if not a Doxia source
      * @since 1.8
      */
     public String getBasedirRelativePath() {
-        return basedirRelativePath;
+        if (!isDoxiaSource()) {
+            return null;
+        }
+        return PathTool.getRelativeFilePath(rootDirectory.getPath(), basedir.getPath());
+    }
+
+    /**
+     * Get the site root relative path of basedir (when a Doxia source). For example {@code markdown}.
+     *
+     * @return the relative path of basedir when a Doxia source, or <code>null</code> if not a Doxia source
+     */
+    private String getBasedirRelativePathAgainstSiteRoot() {
+        if (!isDoxiaSource()) {
+            return null;
+        }
+        return PathTool.getRelativeFilePath(siteRootDirectory.getPath(), basedir.getPath());
     }
 
     /**
-     * Get the relative path to Doxia source from build root.
+     * Get the relative path to Doxia source from build root. The file separators in the returned path are {@code /} regardless of the platform..
      *
      * @return the relative path to Doxia source from build root, or <code>null</code> if not a Doxia source
      * @since 1.8
      */
     public String getDoxiaSourcePath() {
-        return isDoxiaSource() ? (basedirRelativePath + '/' + inputPath) : null;
+        if (!isDoxiaSource()) {
+            return null;
+        } else {
+            for (File sourceDirectory : sourceDirectories) {
+                File sourceFile = new File(sourceDirectory, getBasedirRelativePathAgainstSiteRoot() + '/' + inputPath);
+                if (sourceFile.exists()) {
+                    return PathTool.getRelativeFilePath(rootDirectory.getPath(), sourceFile.getPath())
+                            .replace('\\', '/');
+                }
+            }
+        }
+        return null;
     }
 
     /**
-     * Get url of the Doxia source calculate from given base url.
+     * Get absolute url of the Doxia source calculate from given base url.
+     * Used from Skins to render an edit button.
      *
      * @param base the base url to use
      * @return the resulting url