Skip to content
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

Closed
wants to merge 14 commits into from
Closed

Share TraceQL page #2299

wants to merge 14 commits into from

Conversation

jdbaldry
Copy link
Member

@jdbaldry jdbaldry commented Apr 4, 2023

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 centralized make-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:

  1. You can run make docs
  2. You can see all the images in pages under http://localhost:3002/docs/tempo/latest/traceql/
  3. You can navigate to all links (including to the Loki docs!)
  4. Maybe run doc-validator on the traceql/_index.md file with make doc-validator/traceql/_index.md

Commits:

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>
@jdbaldry jdbaldry marked this pull request as ready for review April 4, 2023 09:56
@jdbaldry jdbaldry self-assigned this Apr 4, 2023
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>
@knylander-grafana knylander-grafana added the type/docs Improvements or additions to documentation label Apr 5, 2023
Copy link
Contributor

@knylander-grafana knylander-grafana left a 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.

@knylander-grafana
Copy link
Contributor

knylander-grafana commented Apr 5, 2023

@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?

@jdbaldry
Copy link
Member Author

jdbaldry commented Apr 6, 2023

Would this change mean that any one who tries to build Tempo docs will have to have the Loki repo cloned locally as well?

You can override the required projects by running make docs PROJECTS=tempo.
That only builds tempo by itself.

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?

Critical errors in Loki or Tempo docs will break local builds but broken links will appear as warnings just as before.

jdbaldry added a commit that referenced this pull request Apr 13, 2023
- 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>
jdbaldry added a commit that referenced this pull request Apr 19, 2023
- 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>
@jdbaldry jdbaldry closed this May 17, 2023
jdbaldry added a commit that referenced this pull request May 22, 2023
- 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>
knylander-grafana added a commit that referenced this pull request Jun 8, 2023
* 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type/docs Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants