Skip to content

Latest commit

 

History

History
71 lines (45 loc) · 5.08 KB

README.md

File metadata and controls

71 lines (45 loc) · 5.08 KB
Raw

REST pipeline

Our REST pipeline creates autogenerated REST API documentation for docs.github.com/rest from the OpenAPI stored in the open-source repository github/rest-api-description.

The pipeline is used to generate data that is used by the docs.github.com site when deployed locally, in preview environments, or in production.

How does it work

A flow chart describing how the automation pipeline for REST generates documentation

A workflow is used to trigger the automation of the REST documentation. The workflow runs automatically on a schedule. The workflow that triggers the REST pipeline also triggers other automation pipelines that use the OpenAPI as the source data:

  • GitHub Apps
  • REST
  • Webhooks

The workflow automatically creates a pull request with the changes (for all three pipelines) and the label github-openapi-bot. The workflow runs the src/rest/scripts/update-files.js script, which creates, deletes, or updates Markdown files in the content/rest directory.

Triggering the workflow sooner than the scheduled time

You can manually run the workflow leaving the source branch input parameter with the default value of main. Running the workflow creates a new pull request in the github/docs-internal repo with the changes.

Triggering the workflow with a different source branch

If there is a pull request that is still unmerged in github/rest-api-description that needs to be propagated to the docs.github.com site, manually run the workflow and provide the branch name of the pull request in the github/rest-api-description repo that you would like to get the changes from. This will create a new pull request in the github/docs-internal repo with the changes.

Local development

To run the REST pipeline locally:

  1. Clone the github/rest-api-description repository inside your local docs-internal repository.
  2. Run src/rest/scripts/update-files.js -s rest-api-description -o rest. Note, by default -o rest is specified, so you can omit it.

About this directory

  • src/rest/api - The source code for the api endpoint used in production that redirects specific anchor links on a page under docs.github.com/rest.
  • src/rest/data - The automatically generated data files created by running this pipeline.
  • src/rest/lib - The source code used in production for the automated documentation generated by the REST pipeline and configuration files edited by content and engineering team members.
    • src/rest/lib/config.json - A configuration file used to specify metadata about the REST pipeline.
  • src/rest/scripts - The scripts and source code used run the REST pipeline, which updates the src/rest/data directory.
    • src/rest/scripts/update-files.js - The entrypoint script that runs the REST pipeline.
  • src/rest/tests - The tests used to verify the REST pipeline.

Configuring the pipeline

The src/rest/lib/config.json file contain metadata used by the content and engineering team to configure the REST pipeline. The file contains the following properties:

  • api-versions - A list of the calendar-date API versions that are available for each version.
  • versionMapping - A mapping of the API version name used in the OpenAPI schema in github/rest-api-description to the version short name used in the github/docs-internal repo.
  • frontmatterDefaults - A list of default frontmatter values to append to each Markdown file in content/rest.
  • targetDirectory - The directory in content where the Markdown files that correspond to this pipeline are located.
  • indexOrder - The order of the children in the index.md file in the targetDirectory. The startsWith keyword lists the directories under targetDirectory that should be listed first. All other automatically created directories are appended to this list.
  • sha - The SHA of the commit in github/rest-api-description that was used to generate the data in src/rest/data and Markdown files in content/rest. This value is automatically updated when the pipeline runs.

Content team

The content writers can manually update parts of the autogenerated Markdown files in content/rest. When new Markdown files are added they will get all of the frontmatter properties defined in the defaultFrontmatter property in src/rest/lib/config.js.

When a new Markdown file is created, a writer can manually change any of the frontmatter except versions. The pipeline will overwrite the versions property on subsequent runs, but will not modify any other frontmatter properties.

Writers can also add an introduction paragraph above the following Markdown comment:

<!-- Content after this section is automatically generated -->

How to get help

Slack: #docs-engineering Repo: github/docs-engineering

If you have a question about the REST pipeline, you can ask in the #docs-engineering Slack channel. If you notice a problem with the REST pipeline, you can open an issue in the github/docs-engineering repository.