Skip to main content

Contributing to Documentation

These docs are powered by Docusaurus and hosted by GitHub Pages. All source material can be found and edited in the alertwest-docs GitHub repo, which is then deployed to this page via a GitHub Actions workflow.

To start, go ahead and checkout the source repository. Inside the repository, you'll find three main directories: docusaurus, asyncapi, and openapi. If you are hoping to write .MDX and contribute directly to docusaurus, see Contributing to Docusaurus. Otherwise, see Contributing to API Reference.

note

All contributions must be submitted in a Pull Request and approved by an organization admin before being pushed to live.

Contributing to API Reference​

At a bare minimum, API reference should be written before starting work on a new service to ensure that application standards are being met. API reference is defined in YAML using AsyncAPI or OpenAPI specification, from which HTML and bindings are automatically generated at deploy time.

Contributing AsyncAPI Specifications​

AsyncAPI service specifications are located in serviceDefinitions with a <ServiceName>/<VersionNumber>/service.yml directory structure. No message definitions should be housed inside of service.yml - instead, messages should be housed in a messages directory and brought into service.yml via a $ref. For example, ALERTWest's top-level service, ImageDispatcher, uses the following service.yml definition:

asyncapi: "2.5.0"
info:
  title: ImageDispatcher
  version: "1.0.0"
  description: |
    Receives S3 upload events, gets the metadata about the S3 object, and publishes that event with metadata to the event bus.

servers:
  eventbridge:
    url: eventbridge
    protocol: https

channels:
  S3ObjectNotification:
    publish:
      message:
        $ref: "../../S3/1.0.0/messages/S3ObjectPutNotification.yml#/S3ObjectPutNotification"
  imageUploaded:
    subscribe:
      message:
        $ref: "../../ImageDispatcher/1.0.0/messages/ImageUploaded.yml#/ImageUploaded"
  panoUploaded:
    subscribe:
      message:
        $ref: "../../ImageDispatcher/1.0.0/messages/PanoUploaded.yml#/PanoUploaded"

You'll notice that not all the messages are defined in this service - only the subscribe messages are defined inside of the service. The producing service should always define the service, then consumers can reference the message using a $ref link.

note

The file name for your service definition must be service.yml to be discovered by the generator script. Message and schema files do not necessarily need to follow a specific convention, although it is recommended to use the message name and schema name as the filenames.

Writing your service definition is relatively straightforward, and you can use other existing service definitions as examples if you need additional reference. After you write your service definitions, submit a PR and, upon approval, your service will automatically be added to the docs and service diagram.

note

The service diagram links services based on the channels/messages that are produced and consumed. Make sure that your consuming service matches the name of the producing service for proper diagram generation.

warning

AsyncAPI references are written relative to the generator's directory. As such, instead of using ./, always back out to the serviceDefinitions level (../../) first, then use a relative reference from there.

Contributing to Docusaurus​

Contributions to Docusaurus directly are made inside the docusaurus directory and are written in either .md or .mdx files. All that is required is to create a new file, either in /blog/ for blog posts or in /docs/ for docs, and start writing. When you are finished, simply open a PR in the alertwest-docs repository and request approval from an administrator.

To learn more about contributing to a Docusaurus-based site, check out Docusaurus' documentation