Documentation Build

Overview

The Datadog documentation contents live in many Github repository:

• jenkinsci/datadog-plugin
• DataDog/integrations-core
• DataDog/integrations-extras
• DataDog/chef-datadog
• DataDog/dd-sdk-android
• Some Internal Datadog repository
• Many others..

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.