Package software.amazon.smithy.docgen.writers

Class DocWriter

java.lang.Object
software.amazon.smithy.utils.AbstractCodeWriter<W>
software.amazon.smithy.codegen.core.SymbolWriter<DocWriter,DocImportContainer>
software.amazon.smithy.docgen.writers.DocWriter
All Implemented Interfaces:
SymbolDependencyContainer
Direct Known Subclasses:
MarkdownWriter
public abstract class DocWriter extends SymbolWriter<DocWriter,DocImportContainer>
A SymbolWriter provides abstract methods that will be used during documentation generation. This allows for other formats to be swapped out without much difficulty.

  • Field Details

    • filename

      protected final String filename
      The full path to the file being written to by the writer.

  • Constructor Details

    • DocWriter

      public DocWriter(DocImportContainer importContainer, String filename)
      Constructor.
      Parameters:
      importContainer - The container to store any imports in.
      filename - The name of the file being written.

  • Method Details

    • writeShapeDocs

      public DocWriter writeShapeDocs(Shape shape, Model model)
      Writes out the content of the shape's documentation trait, if present.

      Smithy's documentation trait is in the CommonMark format, so writers for formats that aren't based on CommonMark will need to convert the value to their format. This includes raw HTML, which CommonMark allows.

      If the shape doesn't have a documentation trait, the writer MAY write out default documentation.

      Parameters:
      shape - The shape whose documentation should be written.
      model - The model whose documentation is being written.
      Returns:
      returns the writer.

    • writeCommonMark

      public abstract DocWriter writeCommonMark(String commmonMark)
      Writes documentation based on a commonmark string.

      Smithy's documentation trait is in the CommonMark format, so writers for formats that aren't based on CommonMark will need to convert the value to their format. This includes raw HTML, which CommonMark allows.

      Parameters:
      commmonMark - A string containing CommonMark-formatted documentation.
      Returns:
      returns the writer.

    • openHeading

      public DocWriter openHeading(String content)
      Writes a heading with the given content.

      closeHeading() will be called to enable cleaning up any resources or context this method creates.

      Parameters:
      content - A string to use as the heading content.
      Returns:
      returns the writer.

    • openHeading

      public DocWriter openHeading(String content, String linkId)
      Writes a heading with the given content and linkId.

      closeHeading() will be called to enable cleaning up any resources or context this method creates.

      Parameters:
      content - A string to use as the heading content.
      linkId - The identifier used to link to the heading.
      Returns:
      returns the writer.

    • closeHeading

      public DocWriter closeHeading()
      Closes the current heading, cleaning any context created for the current level, then writes a blank line.
      Returns:
      returns the writer.

    • openDefinitionList

      public abstract DocWriter openDefinitionList()
      Writes any context needed to open a definition list.

      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.

      Returns:
      returns the writer.

    • closeDefinitionList

      public abstract DocWriter closeDefinitionList()
      Writes any context needed to close a definition list.

      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.

      Returns:
      returns the writer.

    • openDefinitionListItem

      public abstract DocWriter openDefinitionListItem(Consumer<DocWriter> titleWriter)
      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.

      Parameters:
      titleWriter - writes the title or term for the definition list item.
      Returns:
      returns the writer.

    • closeDefinitionListItem

      public abstract DocWriter closeDefinitionListItem()
      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.

      Returns:
      returns the writer.

    • writeAnchor

      public abstract DocWriter writeAnchor(String linkId)
      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.

      Parameters:
      linkId - The anchor's link identifier.
      Returns:
      returns the writer.

    • openTabGroup

      public abstract DocWriter openTabGroup()
      Writes any opening context needed to form a tab group.
      Returns:
      returns the writer.

    • closeTabGroup

      public abstract DocWriter closeTabGroup()
      Writes any context needed to close a tab group.
      Returns:
      returns the writer.

    • openTab

      public abstract DocWriter openTab(String title)
      Writes any context needed to open a tab.
      Parameters:
      title - The title text that is displayed on the tab itself.
      Returns:
      returns the writer.

    • closeTab

      public abstract DocWriter closeTab()
      Writes any context needed to close a tab.
      Returns:
      returns the writer.

    • openCodeBlock

      public abstract DocWriter openCodeBlock(String language)
      Writes any context needed to open a code block.

      For example, a pure HTML writer might write an opening pre tag.

      Parameters:
      language - the language of the block's code.
      Returns:
      returns the writer.

    • closeCodeBlock

      public abstract DocWriter closeCodeBlock()
      Writes any context needed to close a code block.

      For example, a pure HTML writer might write a closing pre tag.

      Returns:
      returns the writer.

    • openCodeTab

      public DocWriter openCodeTab(String title, String language)
      Writes any context needed to open a code block tab.
      Parameters:
      title - The title text that is displayed on the tab itself.
      language - the language of the tab's code.
      Returns:
      returns the writer.

    • closeCodeTab

      public DocWriter closeCodeTab()
      Writes any context needed to close a code block tab.
      Returns:
      returns the writer.

    • openList

      public abstract DocWriter openList(DocWriter.ListType listType)
      Writes any context needed to open a list of the given type.

      For example, a raw HTML writer might write an opening ul tag for an unordered list or an ol tag for an ordered list.

      Parameters:
      listType - The type of list to open.
      Returns:
      returns the writer.

    • closeList

      public abstract DocWriter closeList(DocWriter.ListType listType)
      Writes any context needed to close a list of the given type.

      For example, a raw HTML writer might write a closing ul tag for an unordered list or an ol tag for an ordered list.

      Parameters:
      listType - The type of list to close.
      Returns:
      returns the writer.

    • openListItem

      public abstract DocWriter openListItem(DocWriter.ListType listType)
      Writes any context needed to open a list item of the given type.

      For example, a raw HTML writer might write an opening li tag for a list of any type.

      Parameters:
      listType - The type of list the item is a part of.
      Returns:
      returns the writer.

    • closeListItem

      public abstract DocWriter closeListItem(DocWriter.ListType listType)
      Writes any context needed to close a list item of the given type.

      For example, a raw HTML writer might write a closing li tag for a list of any type.

      Parameters:
      listType - The type of list the item is a part of.
      Returns:
      returns the writer.

    • openAdmonition

      public abstract DocWriter openAdmonition(DocWriter.NoticeType type, Consumer<DocWriter> titleWriter)
      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.

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

    • openAdmonition

      public abstract DocWriter openAdmonition(DocWriter.NoticeType type)
      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.

      Parameters:
      type - The type of admonition to open.
      Returns:
      returns the writer.

    • closeAdmonition

      public abstract DocWriter closeAdmonition()
      Closes the body of an admonition.
      Returns:
      returns the writer.

    • writeBadge

      public abstract DocWriter writeBadge(DocWriter.NoticeType type, String text)
      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.

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