Skip to content

Documentation Build

Austin Lai edited this page Jun 3, 2021 · 16 revisions

Overview

The Datadog documentation contents live in many Github repository:

The idea behind it is to store content where it's created, and to display it where it's consumed.

On every documentation build (triggered by a Branch being merged to master) the script update_pre_build() is called. It pulls all content, transforms it, and puts it where it belongs in the main documentation website.

Since #3749 the build strategy is defined in the file pull_config.yaml which has the following layout:

---
- org_name: <ORG_NAME>
  
  repos:
  - repo_name: <REPOSITORY_NAME>
    
    contents:

    - action: <ACTION_NAME>
      branch: <BRANCH_NAME>
      globs:
      - <GLOBS>
      options:
        <OPTIONS>

With the following variables:

Variable   Description
 <ORG_NAME>  Github organisation name to pull content from.
<REPOSITORY_NAME> Github repository name from <ORG_NAME> to pull content from.
 <BRANCH_NAME> Github branch name from <REPOSITORY_NAME> to pull content from.
<GLOBS> Globs of files to pull from the <ORG_NAME>/<REPOSITORY_NAME>/<BRANCH_NAME> tree.
<ACTION_NAME> Action to apply to the files pulled, refer to the Actions section to see the list of implemented actions.
<OPTIONS> Depending on the <ACTION_NAME>, list of optional parameters.

Actions

integrations

This creates an integration documentation page in https://docs.datadoghq.com/integrations/. To work, <GLOBS> should include paths to:

  • metadata.csv file
  • manifest.json file
  • README.md file

source

This is only for displaying the list of source attribute values available for the Datadog API and shouldn't be used elsewhere.

pull-and-push-files

This pulls a single file from the specified upstream Github repository and displays it in the Documentation. <OPTIONS> should include:

Variable Description
dest_path  Path for the file within the documentation.
file_name New name for the file within the documentation.

pull-and-push-folder

This pulls a folder and all its sub-folders from the specified upstream Github repository and displays it in the Documentation repository with the same layout.

README.md files from the upstream repository are renamed to _index.md to match Hugo internal logic. All links referring to another file from this folder in the upstream repository are replaced with relative links for the documentation repository.

<OPTIONS> should include:

Variable Description
dest_dir  New folder path in the documentation repository to push content to. 
path_to_remove If the upstream folder isn't at the root of the Github repository, enter the path to remove from all files to avoid nested folders within the documentation repository.