Support sphinx integration configuration

JordonPhillips · JordonPhillips · commit 1261271d2598 · 2023-11-03T12:07:51.000+01:00
This updates the sphinx integration to have a built-in configuration
object that it pulls various settings from. When Smithy 1.41 is
released, these will be easily configurable from the
smithy-build.json configuration.

This also slightly changes the doc settings's node parsing function
so it can be discovered by Smithy's NodeMapper, which lets us use
directed codegen's automatic settings mapping, which in turn will
automatically handle passing along integration settings when Smithy
1.41 is released.

One more change will be needed when 1.41 is released: the configure
method will need to be implemented to actually properly set the
settings.
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSettings.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSettings.java
@@ -38,7 +38,7 @@ public record DocSettings(ShapeId service, String format) {
      * @param pluginSettings the {@code ObjectNode} to load settings from.
      * @return loaded settings based on the given node.
      */
-    public static DocSettings from(ObjectNode pluginSettings) {
+    public static DocSettings fromNode(ObjectNode pluginSettings) {
         return new DocSettings(
             pluginSettings.expectStringMember("service").expectShapeId(),
             pluginSettings.getStringMemberOrDefault("format", "sphinx-markdown")
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/SmithyDocPlugin.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/SmithyDocPlugin.java
@@ -39,16 +39,14 @@ public String getName() {
     @Override
     public void execute(PluginContext pluginContext) {
         LOGGER.fine("Beginning documentation generation.");
-        DocSettings settings = DocSettings.from(pluginContext.getSettings());
-
         CodegenDirector<DocWriter, DocIntegration, DocGenerationContext, DocSettings> runner
                 = new CodegenDirector<>();
 
         runner.directedCodegen(new DirectedDocGen());
         runner.integrationClass(DocIntegration.class);
         runner.fileManifest(pluginContext.getFileManifest());
         runner.model(getValidatedModel(pluginContext.getModel()).unwrap());
-        runner.settings(settings);
+        DocSettings settings = runner.settings(DocSettings.class, pluginContext.getSettings());
         runner.service(settings.service());
         runner.performDefaultCodegenTransforms();
         runner.run();
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/integrations/SphinxIntegration.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/integrations/SphinxIntegration.java
@@ -9,6 +9,7 @@
 import static software.amazon.smithy.docgen.core.DocgenUtils.normalizeNewlines;
 import static software.amazon.smithy.docgen.core.DocgenUtils.runCommand;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Set;
 import java.util.logging.Logger;
@@ -22,6 +23,9 @@
 import software.amazon.smithy.docgen.core.sections.sphinx.RequirementsSection;
 import software.amazon.smithy.docgen.core.sections.sphinx.WindowsMakeSection;
 import software.amazon.smithy.docgen.core.writers.SphinxMarkdownWriter;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.node.StringNode;
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.utils.SmithyInternalApi;
 
@@ -47,6 +51,32 @@
  *     build the docs. Any dependencies here will be installed into the environment
  *     used to run {@code sphinx-build}.
  * </ul>
+ *
+ * This integration supports several customization options. To see all those options,
+ * see {@link SphinxSettings}. These settings are configured similarly to the doc
+ * generation plugin settings. Below is an example {@code smithy-build.json} with
+ * sphinx project auto build disabled.
+ *
+ * <pre>{@code
+ * {
+ *     "version": "1.0",
+ *     "projections": {
+ *         "sphinx-markdown": {
+ *             "plugins": {
+ *                 "docgen": {
+ *                     "service": "com.example#DocumentedService",
+ *                     "format": "sphinx-markdown",
+ *                     "integrations": {
+ *                         "sphinx": {
+ *                             "autoBuild": false
+ *                         }
+ *                     }
+ *                 }
+ *             }
+ *         }
+ *     }
+ * }
+ * }</pre>
  */
 @SmithyInternalApi
 public final class SphinxIntegration implements DocIntegration {
@@ -55,12 +85,19 @@ public final class SphinxIntegration implements DocIntegration {
     private static final Logger LOGGER = Logger.getLogger(SphinxIntegration.class.getName());
 
     // The default requirements needed to build the docs.
-    private static final List<String> REQUIREMENTS = List.of(
+    private static final List<String> BASE_REQUIREMENTS = List.of(
         "Sphinx==7.2.6",
         "myst-parser==2.0.0",
         "linkify-it-py==2.0.2"
     );
 
+    private SphinxSettings settings = SphinxSettings.fromNode(Node.objectNode());
+
+    @Override
+    public String name() {
+        return "sphinx";
+    }
+
     @Override
     public byte priority() {
         // Run at the end so that any integration-generated changes can happen.
@@ -83,7 +120,6 @@ public void customize(DocGenerationContext context) {
             ));
             return;
         }
-        // TODO: add some way to disable project file generation
         LOGGER.info("Generating Sphinx project files.");
         writeRequirements(context);
         writeConf(context);
@@ -93,8 +129,13 @@ public void customize(DocGenerationContext context) {
 
     private void writeRequirements(DocGenerationContext context) {
         context.writerDelegator().useFileWriter("requirements.txt", writer -> {
-            writer.pushState(new RequirementsSection(context, REQUIREMENTS));
-            REQUIREMENTS.forEach(writer::write);
+            // Merge base and configured requirements into a single immutable list
+            List<String> requirements = new ArrayList<>(BASE_REQUIREMENTS);
+            requirements.addAll(settings.extraDependencies());
+            requirements = List.copyOf(requirements);
+
+            writer.pushState(new RequirementsSection(context, requirements));
+            requirements.forEach(writer::write);
             writer.popState();
         });
     }
@@ -114,10 +155,11 @@ private void writeConf(DocGenerationContext context) {
                 release = $2S
                 templates_path = ["_templates"]
                 html_static_path = ["_static"]
-                html_theme = "alabaster"
+                html_theme = $3S
                 """,
                 serviceSymbol.getName(),
-                service.getVersion());
+                service.getVersion(),
+                settings.theme());
 
             if (context.docFormat().name().equals(MARKDOWN_FORMAT)) {
                 writer.write("""
@@ -209,6 +251,12 @@ private void writeMakefile(DocGenerationContext context) {
     }
 
     private void runSphinx(DocGenerationContext context) {
+        if (!settings.autoBuild()) {
+            LOGGER.info("Auto-build has been disabled. Skipping sphinx-build.");
+            logManualBuildInstructions(context);
+            return;
+        }
+
         var baseDir = context.fileManifest().getBaseDir();
 
         LOGGER.info("Flushing writers in preparation for sphinx-build.");
@@ -236,7 +284,7 @@ private void runSphinx(DocGenerationContext context) {
             runCommand("./venv/bin/pip install -r requirements.txt", baseDir);
 
             // Finally, run sphinx itself.
-            runCommand("./venv/bin/sphinx-build -M html content build", baseDir);
+            runCommand("./venv/bin/sphinx-build -M " + settings.format() + " content build", baseDir);
 
             System.out.printf(normalizeNewlines("""
                 Successfully built HTML docs. They can be found in "%1$s".
@@ -247,21 +295,22 @@ private void runSphinx(DocGenerationContext context) {
                 environment docs for information on how to activate it: \
                 https://docs.python.org/3/library/venv.html#how-venvs-work
 
-                Once the environment is activated, run `make html` from "%3$s" to \
-                to build the docs, substituting html for whatever format you wish \
+                Once the environment is activated, run `make %4$s` from "%3$s" to \
+                to build the docs, substituting %4$s for whatever format you wish \
                 to build.
 
                 To build the docs without activating the virtual environment, simply \
-                run `./venv/bin/sphinx-build -M html content build` from "%3$s", \
-                similarly substituting html for your desired format.
+                run `./venv/bin/sphinx-build -M %4$s content build` from "%3$s", \
+                similarly substituting %4$s for your desired format.
 
                 See sphinx docs for other output formats you can choose: \
                 https://www.sphinx-doc.org/en/master/usage/builders/index.html
 
                 """),
-                baseDir.resolve("build/html"),
+                baseDir.resolve("build/" + settings.format()),
                 baseDir.resolve("venv"),
-                baseDir
+                baseDir,
+                settings.format()
             );
         } catch (CodegenException e) {
             LOGGER.warning("Unable to automatically build HTML docs: " + e);
@@ -279,13 +328,86 @@ private void logManualBuildInstructions(DocGenerationContext context) {
             instead install them from your system package manager, or another \
             source.
 
-            Once the dependencies are installed, run `make html` from \
+            Once the dependencies are installed, run `make %2$s` from \
             "%1$s". Other output formats can also be built. See sphinx docs for \
             other output formats: \
             https://www.sphinx-doc.org/en/master/usage/builders/index.html
 
             """),
-            context.fileManifest().getBaseDir()
+            context.fileManifest().getBaseDir(),
+            settings.format()
         );
     }
+
+    /**
+     * Settings for sphinx projects, regardless of their intermediate format.
+     *
+     * <p>These settings can be set in the {@code smithy-build.json} file under the
+     * {@code sphinx} key of the doc generation plugin's {@code integrations} config.
+     * The following example shows a {@code smithy-build.json} configuration that sets
+     * the default sphinx output format to be dirhtml instead of html.
+     *
+     * <pre>{@code
+     * {
+     *     "version": "1.0",
+     *     "projections": {
+     *         "sphinx-markdown": {
+     *             "plugins": {
+     *                 "docgen": {
+     *                     "service": "com.example#DocumentedService",
+     *                     "format": "sphinx-markdown",
+     *                     "integrations": {
+     *                         "sphinx": {
+     *                             "format": "dirhtml"
+     *                         }
+     *                     }
+     *                 }
+     *             }
+     *         }
+     *     }
+     * }
+     * }</pre>
+     *
+     * @param format The sphinx output format that will be built automatically during
+     *               generation. The default is html. See
+     *               <a href="https://www.sphinx-doc.org/en/master/usage/builders/index.html">
+     *               sphinx docs</a> for other output format options.
+     * @param theme The sphinx html theme to use. The default is alabaster. If your
+     *              chosen theme requires a python dependency to be added, use the
+     *              {@link #extraDependencies} setting.
+     * @param extraDependencies Any extra python dependencies that should be added to
+     *                          the {@code requirements.txt} file for the sphinx project.
+     *                          These can be particularly useful for custom {@link #theme}s.
+     * @param autoBuild Whether to automatically attempt to build the generated sphinx
+     *                  project. The default is true. This will attempt to discover Python
+     *                  3 on the path, create a virtual environment inside the output
+     *                  directory, install all the dependencies into that virtual environment,
+     *                  and finally run sphinx-build.
+     */
+    public record SphinxSettings(
+            String format,
+            String theme,
+            List<String> extraDependencies,
+            boolean autoBuild
+    ) {
+        /**
+         * Load the settings from an {@code ObjectNode}.
+         *
+         * @param node the {@code ObjectNode} to load settings from.
+         * @return loaded settings based on the given node.
+         */
+        public static SphinxSettings fromNode(ObjectNode node) {
+            List<String> extraDependencies = List.of();
+            if (node.containsMember("extraDependencies")) {
+                var array = node.expectArrayMember("extraDependencies");
+                extraDependencies = array.getElementsAs(StringNode::getValue);
+            }
+            return new SphinxSettings(
+                    node.getStringMemberOrDefault("format", "html"),
+                    node.getStringMemberOrDefault("theme", "alabaster"),
+                    extraDependencies,
+                    node.getBooleanMemberOrDefault("autoBuild", true)
+            );
+        }
+    }
 }
