Skip to content

Documentation Build

Jump to bottom
Heston Hoffman edited this page Oct 10, 2023 · 16 revisions

Overview

Note: The documentation build is only available to Datadog employees.

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.

Don't forget to read our contributing guidelines!

Clone this wiki locally