docs: add website docs and sync-docs-action setup - #52
Merged
Conversation
Adds seven Markdown documentation pages covering the distribution's key topics (overview, getting started, configuration, auto-instrumentation, resource detection, Kubernetes injection, and OTLP exporters), along with the GitHub Actions workflow and transformations.yaml that sync them to the Dash0 website via dash0hq/sync-docs-action. Also adds CLAUDE.md with agentic maintenance instructions that describe which source files are authoritative for each doc page, when to update them, and how to keep the transformations.yaml in sync.
mmanciop
force-pushed
the
docs/website-sync
branch
from
August 5, 2026 10:54
119b200 to
6b6da66
Compare
mmanciop
marked this pull request as draft
August 5, 2026 10:55
…ture Updates the sync-docs-action nav block so the generated python/nav.json uses parentPath "Dash0 Distributions" (which is now established by the foundational distributions/nav.json in the website) and title "Python" rather than "Distributions". This keeps distribution-specific nav.json files focused only on their own pages.
mmanciop
marked this pull request as ready for review
August 5, 2026 11:36
ocelotl
reviewed
Aug 5, 2026
…nsformation Move the relative-link rewrite off the single kubernetes-injection.md entry and into the common section so every current and future doc cross-reference is handled by one mechanism. Uses required: false because the common block runs against every file and most have no cross-reference to rewrite.
CLAUDE.md forbids em-dashes in the website docs. Replace the paired em-dashes in overview.md and kubernetes-injection.md with commas (splitting overview's opening into two sentences), and switch the excluded-package list in auto-instrumentation.md to colon separators. Table default-column cells in configuration.md are left as-is (placeholder, not prose).
The mixed-protocol endpoint rewriting was documented in both configuration.md and exporters.md. Per CLAUDE.md's source-of-truth mapping, port-rewriting logic belongs to exporters.md, so drop the duplicate here. The 'custom ports are never rewritten' behavior remains noted in the OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT table row.
The runnable send-to-Dash0 snippet was identical to the one in getting-started.md. Per CLAUDE.md, quick-start commands belong in getting-started.md, so remove the copy here. The header semantics remain documented in configuration.md's OTEL_EXPORTER_OTLP_HEADERS row.
The sync-docs-action coverage check failed because docs/brainstorms/ and docs/plans/ match coverage.include but have no files: entry. These are internal planning docs, not website content, so list them under coverage.ignore (exact source-relative paths, as the action requires).
The "This page is auto-generated from …" note was visible to readers on the website and felt noise rather than signal. Remove the prepend transformation so synced pages open directly with their content. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…or docs
auto-instrumentation.md:
- Wrap every library table in <div class="two-col-lib-table"> so the
Library column is fixed at 200 px and Instrumentation package takes
the remaining width (requires matching CSS in the website)
- Turn every instrumentation package name into a PyPI link
- Link propagators and excluded packages (opentelemetry-propagator-aws-xray,
opentelemetry-propagator-b3, opentelemetry-exporter-prometheus, etc.)
exporters.md:
- Link dash0-opentelemetry-pyproto, the two pyproto exporter packages,
and the upstream opentelemetry-exporter-otlp-proto-{http,grpc} packages
resource-detection.md:
- Add note after the Kubernetes detector that other k8s.* attributes
(namespace, node, deployment) require the k8sattributesprocessor and
link to the Dash0 Operator and best-practices guide
- Rewrite "Using detectors explicitly": clarify that OTEL_EXPERIMENTAL_
RESOURCE_DETECTORS is only needed with OTEL_CONFIG_FILE declarative
config, explain that the SDK always appends service_instance + otel
so built-in attributes are never displaced, and that all three Dash0
detectors must be listed explicitly in the declarative config path
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
How the sync works
Secrets required before full sync can run
SYNC_DOCUMENTATION_TARGET_REPOSITORY— target website repo (`dash0hq/dash0-website`)SYNC_DOCUMENTATION_TARGET_DIRECTORY— content root in target repo (`src/app/(core)/docs/content`)DASH0_WEBSITE_SYNC_TOKEN— PAT withcontents:write+pull-requests:writeondash0hq/dash0-websiteDependency
The
dash0-websitePR #681 (OpenTelemetry distributions nav setup) must be merged first so the "OpenTelemetry" sidebar section exists before the Python content lands.