Documentation¶

Generation¶

Our docs are configured to be rendered by the static site generator MkDocs with the beautiful Material for MkDocs theme.

Plugins¶

We use a select few MkDocs plugins to achieve the following:

• minify HTML ()
• display the date of the last Git modification of every page ()
• automatically generate docs based on code and docstrings ()
• export the site as a PDF ()

Extensions¶

We also depend on a few Python-Markdown extensions to achieve the following:

• support for emojis, collapsible elements, code highlighting, and other advanced features courtesy of the PyMdown extension suite ()
• ability to inline SVG icons from Material, FontAwesome, and Octicons ()
• allow arbitrary scripts to modify MkDocs input files ()
• automatically generate reference docs for Click-based command line interfaces ()

References¶

All references are automatically available to all pages.

Abbreviations¶

These allow for the expansion of text on hover, useful for acronyms and definitions.

For example, if you add the following to the list of abbreviations:

*[CERN]: European Organization for Nuclear Research

then anywhere you type CERN the organization's full name will appear on hover.

External links¶

All links to external resources should be added to the list of external links rather than defined on a per-page basis, for many reasons:

1. it keeps the Markdown content compact and thus easy to read and modify
2. the ability to re-use a link, even if you forsee no immediate use elsewhere
3. easy automation of stale link detection
4. when links to external resources change, the last date of Git modification displayed on pages will not

Scripts¶

We use some scripts to dynamically modify pages before being processed by other extensions and MkDocs itself, to achieve the following:

• add references to the bottom of every page
• render the status of various aspects of integrations
• enumerate all the dependencies that are shipped with the Datadog Agent

Build¶

We define a hatch environment called docs that provides all the dependencies necessary to build the documentation.

To build and view the documentation in your browser, run the serve command (the first invocation may take a few extra moments):

ddev docs serve

By default, live reloading is enabled so any modification will be reflected in near-real time.

Note: In order to export the site as a PDF, you can use the --pdf flag, but you will need some external dependencies.

Deploy¶

Our CI deploys the documentation to GitHub Pages if any changes occur on commits to the master branch.