Add useDoctreeCache and doctreeCacheDir property

trustin · Apr 4, 2020 · 930ce36 · 930ce36
1 parent 9d9b91a
commit 930ce36
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 16 deletions.
diff --git a/pom.xml b/pom.xml
@@ -12,7 +12,7 @@
   <artifactId>sphinx-maven-plugin</artifactId>
   <packaging>maven-plugin</packaging>
 
-  <version>2.7.1-SNAPSHOT</version>
+  <version>2.8.0-SNAPSHOT</version>
   <url>https://trustin.github.io/sphinx-maven-plugin/</url>
 
   <name>sphinx-maven-plugin</name>

diff --git a/src/main/java/kr/motd/maven/sphinx/SphinxMojo.java b/src/main/java/kr/motd/maven/sphinx/SphinxMojo.java
@@ -70,7 +70,7 @@ public class SphinxMojo extends AbstractMojo implements MavenReport {
             "images/icon_success_sml.gif",
             "images/icon_warning_sml.gif",
             "images/newwindow.png",
-            "images",
+            "images"
     };
 
     /**
@@ -82,32 +82,32 @@ public class SphinxMojo extends AbstractMojo implements MavenReport {
     /**
      * Directory where reports will go.
      */
-    @Parameter(defaultValue = "${project.reporting.outputDirectory}", required = true, readonly = true)
+    @Parameter(defaultValue = "${project.reporting.outputDirectory}", required = true)
     private File outputDirectory;
 
     /**
      * The base URL of the Sphinx binary, which will be used when downloading the Sphinx binary; must start
      * with {@code http://}, {@code https://} or {@code file://}.
      */
-    @Parameter(property = "sphinx.binUrl", readonly = true)
+    @Parameter(property = "sphinx.binUrl")
     private String binaryUrl = SphinxRunner.DEFAULT_BINARY_URL;
 
     /**
      * The directory for Sphinx binary cache.
      */
-    @Parameter(property = "sphinx.binCacheDir", defaultValue = "${settings.localRepository}/kr/motd/maven/sphinx-binary", required = true, readonly = true)
+    @Parameter(property = "sphinx.binCacheDir", defaultValue = "${settings.localRepository}/kr/motd/maven/sphinx-binary", required = true)
     private File binaryCacheDir;
 
     /**
      * The environment variables to set when launching Sphinx.
      */
-    @Parameter(property = "sphinx.env", readonly = true)
+    @Parameter(property = "sphinx.env")
     private Map<String, String> environments = Collections.emptyMap();
 
     /**
      * The path to Graphviz {@code dot} binary.
      */
-    @Parameter(property = "sphinx.dotBin", readonly = true)
+    @Parameter(property = "sphinx.dotBin")
     private String dotBinary;
 
     /**
@@ -154,6 +154,19 @@ public class SphinxMojo extends AbstractMojo implements MavenReport {
     @Parameter(property = "sphinx.skip", defaultValue = "false", required = true, alias = "skip")
     private boolean skip;
 
+    /**
+     * Whether Sphinx should use doctree cache.
+     */
+    @Parameter(property = "sphinx.useDoctreeCache", defaultValue = "false", required = true, alias = "useDocTreeCache")
+    private boolean useDoctreeCache;
+
+    /**
+     * The directory containing Sphinx doctree cache.
+     */
+    @Parameter(property = "sphinx.doctreeCacheDir", defaultValue = "${project.reporting.outputDirectory}/.doctrees", required = true, alias = "doctreeCacheDir")
+    private File doctreeCacheDir;
+
+
     @Override
     public void execute() throws MojoExecutionException {
         if (skip) {
@@ -164,6 +177,7 @@ public void execute() throws MojoExecutionException {
         final File sourceDirectory = canonicalize(this.sourceDirectory);
         final File outputDirectory = getReportOutputDirectory();
         final File binaryCacheDir = canonicalize(this.binaryCacheDir);
+        final File doctreeCacheDir = useDoctreeCache ? canonicalize(this.doctreeCacheDir) : null;
 
         // to avoid Maven overriding resulting index.html, update index.rst to force re-building of index
         if (isHtmlReport()) {
@@ -184,7 +198,7 @@ public void log(String msg) {
                     });
 
             getLog().info("Running Sphinx; output will be placed in " + outputDirectory);
-            final List<String> args = getSphinxRunnerCmdLine(sourceDirectory, outputDirectory);
+            final List<String> args = getSphinxRunnerCmdLine(sourceDirectory, outputDirectory, doctreeCacheDir);
             if (sphinxRunner.run(sourceDirectory, args) != 0) {
                 throw new MavenReportException("Sphinx report generation failed");
             }
@@ -331,8 +345,8 @@ public boolean canGenerateReport() {
     /**
      * Build the Sphinx Command line options.
      */
-    private List<String> getSphinxRunnerCmdLine(File sourceDirectory, File outputDirectory) {
-        List<String> args = new ArrayList<>();
+    private List<String> getSphinxRunnerCmdLine(File sourceDirectory, File outputDirectory, File doctreeCacheDir) {
+        final List<String> args = new ArrayList<>();
 
         if (verbose) {
             args.add("-v");
@@ -353,6 +367,11 @@ private List<String> getSphinxRunnerCmdLine(File sourceDirectory, File outputDir
             args.add("-E");
         }
 
+        if (doctreeCacheDir != null) {
+            args.add("-d");
+            args.add(doctreeCacheDir.getPath());
+        }
+
         if (tags != null && !tags.isEmpty()) {
             for (String tag : tags) {
                 args.add("-t");

diff --git a/src/site/sphinx/conf.py b/src/site/sphinx/conf.py
@@ -20,8 +20,8 @@
 
 project = u'sphinx-maven-plugin'
 copyright = u'2016, Trustin Lee et al'
-version = '2.7'
-release = '2.7.0'
+version = '2.8'
+release = '2.8.0'
 
 # General options
 needs_sphinx = '1.0'
@@ -36,7 +36,7 @@
 source_suffix = ['.rst', '.md']
 source_encoding = 'utf-8-sig'
 source_parsers = {
-  '.md': CommonMarkParser
+    '.md': CommonMarkParser
 }
 
 # HTML options

diff --git a/src/site/sphinx/configuration.rst b/src/site/sphinx/configuration.rst
@@ -6,9 +6,9 @@ Configuration
 
 The ``sphinx-maven`` plugin has these configuration options:
 
-======================== ================================================================================================= ========================================
+======================== ================================================================================================= ==================================================
 Parameter                Description                                                                                       Default value
-======================== ================================================================================================= ========================================
+======================== ================================================================================================= ==================================================
 ``sourceDirectory``      The directory containing the documentation source.                                                ``${basedir}/src/site/sphinx``
 ``outputDirectory``      The directory where the generated output will be placed.                                          ``${project.reporting.outputDirectory}``
 ``binaryUrl``            The URL of the Sphinx executable binary. Must start with ``file:``, ``http:`` or ``https:``       <automatic>
@@ -25,7 +25,9 @@ Parameter                Description
 ``tags``                 Additional tags to pass to Sphinx. See `Including content based on tags`_ for more information.
 ``asReport``             Whether documentation should be generated as a project report (keep default Maven site).          ``false``
 ``skip``                 Whether Sphinx execution should be skipped.                                                       ``false``
-======================== ================================================================================================= ========================================
+``useDoctreeCache``      Whether doctree cache should be used.                                                             ``false``
+``doctreeCacheDir``      The directory containing Sphinx doctree cache. Used only when ``useDoctreeCache`` is ``true``     ``${project.reporting.outputDirectory}/.doctrees``
+======================== ================================================================================================= ==================================================
 
 Sample Documentation Config
 ===========================