### What does this PR do? Moves the maintained Datadog Agent developer documentation from `docs/public/` to `doc/`, together with its site support files. Published page URLs stay the same. ### Motivation AI coding agents use repository documentation to guide their changes. Moving maintained guidance into `doc/` gives them one directory to consult, with unfinished and deprecated pages kept in `docs/` until they are reviewed for incorporation or removal. ### Describe how you validated your changes ```text $ dda run docs build Syncing dependencies Build started No issues found Build finished in 3.80s $ dda run docs check-links 🔍 6852 Total (in 973ms) 🔗 989 Unique ✅ 6566 OK 🚫 0 Errors 👻 200 Excluded ⛔ 86 Unsupported $ dda inv linter.docs-links Synchronizing dependencies The documentation references this repository properly $ dda inv invoke-unit-tests.run --tests=docs_repo_links,docs_links Synchronizing dependencies ................................ ---------------------------------------------------------------------- Ran 32 tests in 0.087s OK ... ---------------------------------------------------------------------- Ran 3 tests in 0.024s OK Running tests from module docs_repo_links_tests Running tests from module docs_links_tests ``` ### Additional Notes `docs/README.md` lists every retained page and its reason. Unpublished pages, deprecated component guidance, and empty placeholders remain temporarily while their content is reviewed for removal or incorporation. Co-authored-by: ofek.lev <ofek.lev@datadoghq.com>
6.9 KiB
Writing developer docs
This site is built by Zensical, using its classic theme variant for compatibility with Material for MkDocs.
See the developer documentation reference for the site's configuration, variable injection, and theme customizations.
You can serve documentation locally with the dda run docs serve command.
Once the site is built with dda run docs build, dda run docs check-links resolves every link it contains, which dda run docs build --check does for you in one step.
Organization
Add and maintain developer documentation in <<<repo("doc")>>>.
The site structure is defined by the nav key in the <<<repo("mkdocs.yml")>>> file.
We strive to follow the principles of the Diátaxis documentation framework.
When adding new pages, first think about what it is exactly that you are trying to document. For example, if you intend to write about something everyone must follow as a standard practice it would be classified as a guideline whereas a short piece about performing a particular task would be a how-to.
After deciding the kind of content, further segment the page under logical groupings for easier navigation.
Independent navigation roots
Use independent navigation roots rarely. Most topics belong under the existing How-to, Tutorials, Guidelines, or Reference tabs. Add a root only when a substantial, self-contained area needs its own set of top-level topics, as Architecture does.
To configure a root, define a top-level section in nav in <<<repo("mkdocs.yml")>>> and put its landing page first. Add that page's generated URL to extra.navigation_roots, relative to the site root, without the deployment prefix or a Markdown source path. For example, Architecture's landing page is configured as architecture/.
extra:
navigation_roots:
- url: architecture/
See the navigation roots reference for available options, behavior, and limitations.
Ordered lists
Each item in an ordered list should start with 1. and let rendering handle the rest. This is recommended for two reasons:
- Changes to the list size do not require re-numbering unmodified items and therefore reduces the diff when reviewing.
- Rendering will expose improper formatting by having the sequence broken rather than hiding such issues.
Line continuations
For prose where the rendered content should have no line breaks, always keep the Markdown on the same line. This removes the need for any stylistic enforcement and allows for IDEs to intelligently wrap as usual.
/// tip When you wish to force a line continuation but stay within the block, indent by 2 spaces from the start of the text and end the block with a new line. For example, the following shows how you would achieve a multi-line ordered list item:
-
Markdown
1. first line second line 1. third line -
Rendered
-
first line
second line
-
third line
-
///
Emphasis
When you want to call something out, use admonitions rather than making large chunks of text bold or italicized. The latter is okay for small spans within sentences.
Here's an example:
-
Markdown
/// info Lorem ipsum ... /// -
Rendered
/// info Lorem ipsum ... ///
Links
Always use inline links rather than reference links.
The only exception to that rule is links that many pages may need to reference. Such links may be added to <<<repo("doc/.snippets/links.txt", "this file")>>> that all pages are able to reference.
Repository paths
Never write a link to a file or directory of this repository by hand. Give the repo macro a path relative to the repository root and it links files as blob, links directories as tree, and fails the build when the path no longer exists. Links to anything else the repository hosts, such as a pull request, are still written by hand.
Links point at the branch being built rather than always at main, so a preview built from a pushed branch links to that branch's own files.
-
Markdown
<<% raw %>>- Directory <<<repo("bazel/rules")>>> - File <<<repo("MODULE.bazel")>>> - Line in file <<<repo( ".gitlab-ci.yml", match="^stages:", )>>><<% endraw %>> -
Rendered
-
Directory
<<<repo("bazel/rules")>>>
-
File
<<<repo("MODULE.bazel")>>>
-
Line in file
<<<repo( ".gitlab-ci.yml", match="^stages:", )>>>
-
The link text defaults to the path in backticks. A second argument replaces it and is itself Markdown, so add backticks yourself when you want a short monospaced label.
To link a single line, pass match with a regular expression that matches exactly one line of the file, as above. The search is unanchored, so ^ and $ are available to pin the expression to the start or end of a line, and characters such as ( need escaping to match literally. The line number is resolved on every build and therefore never drifts, so never write one by hand.
When a link will not do, such as in a raw HTML attribute, repo_url validates the same path and match arguments but renders only the URL:
-
Markdown
<<% raw %>><a href="<<<repo_url( ".gitlab-ci.yml", match="^stages:", )>>>">the stage list</a><<% endraw %>> -
Rendered
<a href="<<<repo_url( ".gitlab-ci.yml", match="^stages:", )>>>">the stage list
The macro rejects Markdown pages under doc, which are linked relatively so that readers stay on this site.
/// warning
Macros are rendered everywhere on a page, including inside fenced code blocks. To show a macro rather than call it, wrap it in <<<"<<% raw %>>">>> and <<<"<<% endraw %>>">>> on the same line, the way the example above does. Putting those tags on their own lines leaves blank lines behind.
Macros do not run inside <<<repo("doc/.snippets")>>>, whose files are appended to each page after macros have already been rendered. ///
Abbreviations
Abbreviations like DSD may be added to <<<repo("doc/.snippets/abbrs.txt", "this file")>>> which will make it so that a tooltip will be displayed on hover.