Package software.amazon.smithy.docgen.integrations

Class SphinxIntegration

java.lang.Object
software.amazon.smithy.docgen.integrations.SphinxIntegration
All Implemented Interfaces:
SmithyIntegration<DocSettings,DocWriter,DocGenerationContext>, DocIntegration
public final class SphinxIntegration extends Object implements DocIntegration
Adds Sphinx project scaffolding for compatible formats.

This integration runs in low priority to allow other integrations to generate files that will be picked up by sphinx-build. To have an integration reliably run after this, override SmithyIntegration.runAfter() with the output of name() in the list. Similarly, to guarantee an integration is run before this, override SmithyIntegration.runBefore() with the same argument.

To customize the project files generated by this integration, you can make use of SmithyIntegration.interceptors(C) to intercept and modify the files before they're written. The following named code sections are used:

  • ConfSection: Creates the conf.py
  • MakefileSection: Creates the Makefile build script for unix.
  • WindowsMakeSection: Creates the make.bat build script for Windows.
  • RequirementsSection: Creates the requirements.txt used to build the docs. Any dependencies here will be installed into the environment used to run sphinx-build.
This integration supports several customization options. To see all those options, see SphinxIntegration.SphinxSettings. These settings are configured similarly to the doc generation plugin settings. Below is an example smithy-build.json with sphinx project auto build disabled. 

 {
     "version": "1.0",
     "projections": {
         "sphinx-markdown": {
             "plugins": {
                 "docgen": {
                     "service": "com.example#DocumentedService",
                     "format": "sphinx-markdown",
                     "integrations": {
                         "sphinx": {
                             "autoBuild": false
                         }
                     }
                 }
             }
         }
     }
 }

  • Constructor Details

    • SphinxIntegration

      public SphinxIntegration()

  • Method Details

    • name

      public String name()
      Description copied from interface: SmithyIntegration
      Gets the name of the integration.

      This name is referred to when ordering the graph of integrations. The name defaults to the canonical class name if not overridden.

      Specified by:
      name in interface SmithyIntegration<DocSettings,DocWriter,DocGenerationContext>
      Returns:
      Returns the integration name.

    • priority

      public byte priority()
      Description copied from interface: SmithyIntegration
      Gets the priority ordering relative to the topologically ordered integration graph determined by SmithyIntegration.runBefore() and SmithyIntegration.runAfter().

      Higher numbers come before lower numbers.

      When ordering, implementations must not allow cycles, and no two integrations may have the same name.

      Specified by:
      priority in interface SmithyIntegration<DocSettings,DocWriter,DocGenerationContext>
      Returns:
      Returns the priority order.

    • configure

      public void configure(DocSettings settings, ObjectNode integrationSettings)
      Description copied from interface: SmithyIntegration
      Configures the integration.

      This provides access to both the parsed settings for the generator and an unparsed ObjectNode containing settings for this particular integration.

      The following smithy-build.json file contains an example of how this configuration will be set. 

      
 {
     "version": "1.0",
     "projections": {
         "codegen-projection": {
             "plugins": {
                 "code-generator": {
                     "service": "com.example#DocumentedService",
                     "integrations": {
                         "my-integration": {
                             "example-setting": "foo"
                         }
                     }
                 }
             }
         }
     }
 }

      In this example, an integration whose SmithyIntegration.name() is my-integration Would receive the extra settings from the key of the same name within the integrations node.

      Integrations SHOULD use modeled traits as much as possible to drive configuration. This is intended for configuration that doesn't make sense as a trait, such as configuring a documentation theme.

      Specified by:
      configure in interface SmithyIntegration<DocSettings,DocWriter,DocGenerationContext>
      Parameters:
      settings - Settings used to generate code.
      integrationSettings - Settings used to configure integrations.

    • docFormats

      public List<DocFormat> docFormats(DocSettings settings)
      Description copied from interface: DocIntegration
      Adds DocFormats to the list of supported formats.

      When resolving the format implementation, the first format found with a matching name will be used. Use SmithyIntegration.priority() to adjust which integration is seen first.

      Specified by:
      docFormats in interface DocIntegration
      Parameters:
      settings - The documentation generation settings.
      Returns:
      A list of formats to add.

    • customize

      public void customize(DocGenerationContext context)
      Description copied from interface: SmithyIntegration
      Allows generators to write additional files, perform additional tasks, and interact directly with a FileManifest used to write files to the plugin's output.

      This method should generally be invoked at the end of the code generation process.

      Specified by:
      customize in interface SmithyIntegration<DocSettings,DocWriter,DocGenerationContext>
      Parameters:
      context - Code generation context that can be queried when writing additional files.