Package software.amazon.smithy.docgen.writers

Class SphinxMarkdownWriter

java.lang.Object
software.amazon.smithy.utils.AbstractCodeWriter<W>
software.amazon.smithy.codegen.core.SymbolWriter<DocWriter,DocImportContainer>
software.amazon.smithy.docgen.writers.DocWriter
software.amazon.smithy.docgen.writers.MarkdownWriter
software.amazon.smithy.docgen.writers.SphinxMarkdownWriter
All Implemented Interfaces:
SymbolDependencyContainer
public final class SphinxMarkdownWriter extends MarkdownWriter
Writes documentation in CommonMark-based format for the Sphinx doc build system.

The specific markdown parser being written for is MyST with the following extensions enabled: linkify and colon_fence

  • Constructor Details

    • SphinxMarkdownWriter

      public SphinxMarkdownWriter(String filename)
      Constructs a SphinxMarkdownWriter.
      Parameters:
      filename - The full path to the file being written to.

  • Method Details

    • openDefinitionListItem

      public DocWriter openDefinitionListItem(Consumer<DocWriter> titleWriter)
      Description copied from class: DocWriter
      Writes any context needed to open a definition list item.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Overrides:
      openDefinitionListItem in class MarkdownWriter
      Parameters:
      titleWriter - writes the title or term for the definition list item.
      Returns:
      returns the writer.

    • closeDefinitionListItem

      public DocWriter closeDefinitionListItem()
      Description copied from class: DocWriter
      Writes any context needed to close a definition list item.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Overrides:
      closeDefinitionListItem in class MarkdownWriter
      Returns:
      returns the writer.

    • writeAnchor

      public DocWriter writeAnchor(String linkId)
      Description copied from class: DocWriter
      Writes a linkable element to the documentation with the given identifier.

      The resulting HTML should be able to link to this anchor with #linkId.

      For example, a direct HTML writer might create a span tag with the given string as the tag's id, or modify the next emitted tag to have the given id.

      Overrides:
      writeAnchor in class MarkdownWriter
      Parameters:
      linkId - The anchor's link identifier.
      Returns:
      returns the writer.

    • openTabGroup

      public DocWriter openTabGroup()
      Description copied from class: DocWriter
      Writes any opening context needed to form a tab group.
      Overrides:
      openTabGroup in class MarkdownWriter
      Returns:
      returns the writer.

    • closeTabGroup

      public DocWriter closeTabGroup()
      Description copied from class: DocWriter
      Writes any context needed to close a tab group.
      Overrides:
      closeTabGroup in class MarkdownWriter
      Returns:
      returns the writer.

    • openTab

      public DocWriter openTab(String title)
      Description copied from class: DocWriter
      Writes any context needed to open a tab.
      Overrides:
      openTab in class MarkdownWriter
      Parameters:
      title - The title text that is displayed on the tab itself.
      Returns:
      returns the writer.

    • closeTab

      public DocWriter closeTab()
      Description copied from class: DocWriter
      Writes any context needed to close a tab.
      Overrides:
      closeTab in class MarkdownWriter
      Returns:
      returns the writer.

    • openAdmonition

      public DocWriter openAdmonition(DocWriter.NoticeType type, Consumer<DocWriter> titleWriter)
      Description copied from class: DocWriter
      Opens an admonition with a custom title.

      An admonition is an emphasized callout that typically have color-coded severity. A warning admonition, for example, might have a yellow or red banner that emphasizes the importance of the body text.

      Overrides:
      openAdmonition in class MarkdownWriter
      Parameters:
      type - The type of admonition to open.
      titleWriter - A consumer that writes out the title.
      Returns:
      returns the writer.

    • openAdmonition

      public DocWriter openAdmonition(DocWriter.NoticeType type)
      Description copied from class: DocWriter
      Opens an admonition with a default title.

      An admonition is an emphasized callout that typically have color-coded severity. A warning admonition, for example, might have a yellow or red banner that emphasizes the importance of the body text.

      Overrides:
      openAdmonition in class MarkdownWriter
      Parameters:
      type - The type of admonition to open.
      Returns:
      returns the writer.

    • closeAdmonition

      public DocWriter closeAdmonition()
      Description copied from class: DocWriter
      Closes the body of an admonition.
      Overrides:
      closeAdmonition in class MarkdownWriter
      Returns:
      returns the writer.

    • writeBadge

      public DocWriter writeBadge(DocWriter.NoticeType type, String text)
      Description copied from class: DocWriter
      Writes text as a badge.

      Implementations SHOULD write inline.

      A badge in this context means text enclosed in a color-coded rectangular shape. The color should be based on the given type.

      Overrides:
      writeBadge in class MarkdownWriter
      Parameters:
      type - The notice type of the badge that determines styling.
      text - The text to put in the badge.
      Returns:
      returns the writer.