-
Notifications
You must be signed in to change notification settings - Fork 482
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Share TraceQL page #2299
Share TraceQL page #2299
Conversation
Allows it to be reused in other projects with the `docs/shared` shortcode. For more information about the shortcode, refer to https://grafana.com/docs/writers-toolkit/writing-guide/shortcodes/#docsshared-shortcode. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
The content is applicable to all product dimensions. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
It is preferred according to https://grafana.com/docs/writers-toolkit/writing-guide/image-guidelines/. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
…unts Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for doing these updates! Preview build looks clean.
@jdbaldry I just tried deleting my local clone of the Loki repo and make docs failed because the repo wasn't found. Would this change mean that any one who tries to build Tempo docs will have to have the Loki repo cloned locally as well? Does this also tie Tempo docs to Loki docs? If there is an error in the Loki docs, does that mean the Tempo docs won't build? |
You can override the required projects by running
Critical errors in Loki or Tempo docs will break local builds but broken links will appear as warnings just as before. |
- Adds ability to build multiple projects simultaneously using, for example, `make docs PROJECTS='grafana grafana-cloud'`. - Adds `make doc-validator` which runs [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) on all documentation. Using a centralized script will help ensure consistency in workflow across all projects. This PR incorporates some of the improvements from #2299 without introducing significant CI changes. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
- Adds ability to build multiple projects simultaneously using, for example, `make docs PROJECTS='grafana grafana-cloud'`. - Adds `make doc-validator` which runs [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) on all documentation. Using a centralized script will help ensure consistency in workflow across all projects. This PR incorporates some of the improvements from #2299 without introducing significant CI changes. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
- Adds ability to build multiple projects simultaneously using, for example, `make docs PROJECTS='grafana grafana-cloud'`. - Adds `make doc-validator` which runs [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) on all documentation. Using a centralized script will help ensure consistency in workflow across all projects. This PR incorporates some of the improvements from #2299 without introducing significant CI changes. Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Use centralized make-docs script from Writers' Toolkit - Adds ability to build multiple projects simultaneously using, for example, `make docs PROJECTS='grafana grafana-cloud'`. - Adds `make doc-validator` which runs [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) on all documentation. Using a centralized script will help ensure consistency in workflow across all projects. This PR incorporates some of the improvements from #2299 without introducing significant CI changes. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update make-docs procedure Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Add doc-validator workflow Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix docs source directory Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update to latest release and skip image validation Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update doc-validator version https://github.com/grafana/technical-documentation/blob/main/tools/cmd/doc-validator/CHANGELOG.md Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update workflow for new docs directory structure Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix one link Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update make-docs procedure and doc-validator workflow Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix doc-validator linting errors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Also build with helm-charts/tempo-distributed docs Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix doc-validator linting errors in helm-charts/tempo-distributed Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Add descriptions to pages * Added descriptions to frontmatter * Fix number formatting * Fix validator errors * Fix build error * Fix validator issues * Fix broken link * Fix query syntax anchor link Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix title to match first heading Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Mount documentation so that both documentation sets can be tested together Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Cause an error to double check CI Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix pwd invocation Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Use single step Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Avoid symlinks since doc-validator doesn't follow them grafana/technical-documentation#713 Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Revert "Cause an error to double check CI" This reverts commit c238180. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update make-docs procedure Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Break a relref for testing doc-validator CI Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update doc-validator to v3.0.0 ## 3.0.0 ### Added - Structured output for use with [`reviewdog`](https://github.com/reviewdog/reviewdog). You can achieve the original error output by piping the output to the following `jq` expression: `jq -r '"ERROR: \(.location.path):\(.location.range.start.line):\(.location.range.start.column): \(.message)"'`. - Suggestions for simple link fixes. In GitHub, [`reviewdog`](https://github.com/reviewdog/reviewdog) comments these suggestions for convenient replacement. - Support for anchors referring to repeated headings. In the case that a page has multiple headings that share the same text, the renderer appends a zero indexed, numbered suffix to the identifier. For example, when there are two headings that are both "Heading text", the first anchor identifier is `heading-text` and the second is `heading-text-1`. - Error when running `doc-validator` on no files. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Accept doc-validator suggestion Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Kim Nylander <kim.nylander@grafana.com> Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
What this PR does:
Prepares the TraceQL index page for being reused in other projects with the
docs/shared
shortcode.It uses the
relref
shortcode to get build time link checking including the links to Loki.The behavior is not perfectly correct given that it checks for pages in the most recent commit of Loki rather than the actually released content but I think this is still a step forward over blind linking.
The
make docs
target is updated to use the centralizedmake-docs
script from Writers' Toolkit.The script makes it easy to build multiple documentation sets together, even at specific versions if required.
For now, it only concerns itself with building Loki and Tempo side-by-side for
relref
link checking.Things for reviewer to check:
make docs
doc-validator
on thetraceql/_index.md
file withmake doc-validator/traceql/_index.md
Commits:
Move traceql to shared directory
Add 'Grafana Cloud' and 'Enterprise' labels to TraceQL
Use relrefs for docs links, partial URIs for blog links
Update Makefile to support cross repository docs builds
Clean whitespace
Prefer "preceding" over "above"
Prefer one line per sentence for better line based diffing
Use object storage for traceql image assets
Try building multiple documentation sets in CI