Add local documentation webserver

[jdbaldry]

This PR reorganizes the documentation into the directory structure consistent with all other projects documented at https://grafana.com/docs/.

It adds a Makefile in the docs/ directory that has targets for running a local webserver to view the generated Hugo site at http://localhost:3002/docs/ebpf-autoinstrument/latest/. A workflow is added to automatically update the Makefile and supporting files from the centralized source in Writers' Toolkit. I've added myself as a CODEOWNER and will ensure that I promptly validate, review, and merge those update PRs.

It also adds a doc-validator workflow that lints technical documentation. The tool is still a work in progress but it provides useful guidance for correct use of the Hugo relref shortcode, checking link anchors exist in destination pages, as well as other linting checks. It provides comments to PRs automatically and for trivial fixes, it even provides suggestions. Please report any bugs to me in #docs-squad on Slack or as a GitHub issue in https://github.com/grafana/technical-documentation/issues.

You can run doc-validator locally with make doc-validator. It has structured JSON output that can be made more human readable using something like: make -s doc-validator | jq -r '"ERROR: \(.location.path):\(.location.range.start.line // 1):\(.location.range.start.column // 1): \(.message). Suggestion: \(.suggestions[0].text // "")"

TO DO (team):

• Some questions about website publishing:
  • At what URL do we want documentation to be published?
    Do we want to publish versioned documentation at this point in time? I don't see any tags or long lived version branches so I'm expecting that we are happy to just publish whatever is in main.
• Mermaid charts need to be rendered and embedded. We don't yet have Mermaid support in the website (https://github.com/grafana/website/pull/9196).
• All pages need a description. Requires either maintainer or technical writer to perform. For some guidance, refer to https://grafana.com/docs/writers-toolkit/writing-guide/front-matter/#description-required.
• Need consistent name, I've seen each of the following throughout the docs.
  • eBPF autoinstrument
  • eBPF autoinstrumenter
  • eBPF Autoinstrument
  • Auto-instrumenter

[grcevski]

LGTM! Thanks!

There's seems to be a validation failure in the pipeline that needs to be looked at.

[grcevski]

Good point. We started the conversation on naming few weeks ago, we'll come up with a name and re-brand everything by end of the month.

[jdbaldry]

Indeed there is, this is doc-validator complaining that we don't have descriptions on the pages. These are required for published documentation and need someone familiar with the content to write them or for a technical writer to come in and write them. Some brief guidance is available in https://grafana.com/docs/writers-toolkit/writing-guide/front-matter/#description-required.

[grcevski]

OK, great, I can do that work. I'll make a PR with the required changes on top of this branch, so we can merge that before we merge this PR fully. Thanks!

[jdbaldry]

OK, great, I can do that work. I'll make a PR with the required changes on top of this branch, so we can merge that before we merge this PR fully. Thanks!

Great plan!

[grcevski]

I made a PR with these changes: #170

[grcevski]

Hm, my PR still fails with this error:

reviewdog: parse error: failed to unmarshal rdjsonl (Diagnostic): proto: syntax error (line 1:1): invalid value docs

[jdbaldry]

Thanks! I'll take a look and see what's going wrong between doc-validator and reviewdog.

[codecov-commenter]

Codecov Report

Merging #169 (4733e0c) into main (72938d7) will decrease coverage by 42.39%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##             main     #169       +/-   ##
===========================================
- Coverage   81.46%   39.08%   -42.39%     
===========================================
  Files          35       34        -1     
  Lines        2466     2410       -56     
===========================================
- Hits         2009      942     -1067     
- Misses        337     1410     +1073     
+ Partials      120       58       -62     

Flag	Coverage Δ
integration-test	?
unittests	39.08% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

see 27 files with indirect coverage changes

[jdbaldry]

I'm going to merge this so that any future docs work doesn't cause conflicts. Hit me up if you need any follow up PRs to fix if you spot anything that's not right.