Introducing The Overhauled NativeLink Documentation

[blakehatch]

This is a total overhaul of our documentation

Preview Deployment: nativelink-31n.pages.dev

This docs update implements two primary ethos:

• A decision tree structure to create a catered experience for our multiple different customer profiles (Cloud, On-Prem, Contributor, etc)
• Attempts to maintain adherance to the Diátaxis documentation system.

I have made attempts to create as little new content in this documentation as possible, pulling from many helpful contributions of useful peer-reviewed documentation most notably examples of actual production configs and deployments from @kubevalet.

:::Note
When reviewing please focus on the structure and avoid diving into nits on the content due to the scale of this, obviously blatantly incorrect content can be addressed here. This is intended to be a jumping-off point for many updates and improvements for other maintainers.

In other words to fix the cold-start problem the sparseness of the previous docs presented.

So if you want to completely change a section, please open a new PR on top of this one to overhaul individual sections.
:::

Notable new sections of content include:

FAQ

• Helpful for answering miscellaneous questions on some of our esoteric tooling. Will help make our product less intimidating for first-time onlookers

Introduction

• Routes all of our different user personas to their intended destination so they don't have to slog through irrelevant documentation.

Bug fixes

• Fixed warning to caution parsing
• Got rid of "(String)" which was scattered through the autogen reference creating a messy look.
• Fixed many unecessary Vale vocab restrictions

---

This change is 

[MarcusSorealheis]

Can you post a link to the preview of the rendering of the documentation?

Reviewable status: 0 of 1 LGTMs obtained, and pending CI: Bazel Dev / ubuntu-22.04, Cargo Dev / macos-13, Cargo Dev / ubuntu-22.04, Installation / macos-13, Installation / ubuntu-22.04, Local / ubuntu-22.04, Publish image, Publish nativelink-worker-init, Publish nativelink-worker-lre-cc, Remote / large-ubuntu-22.04, docker-compose-compiles-nativelink (20.04), docker-compose-compiles-nativelink (22.04), macos-13, pre-commit-checks, windows-2022 / stable

[aaronmondal]

@blakehatch Before we go into the details:

• Split off the changes to metaphase.ts and md_to_mdx.ts into one or two separate PRs.

For this PR:

• The following files should not be part of the PR as they're autogenerated. Instead they should be in the docs/.gitignore:

  • chromium.mdx
  • kubernetes.mdx
  • setup.mdx
  • I may have overlooked a file or two (like the config explantations?), please double-check.

• Revisit the change to accept.txt. Note that in it's current state your changes are not entirely correct. Various terms added here are not correct. For instance size_partitioning is not a word and lru should only be allowed capitalized as LRU.

• Please make sure that any non-generated (i.e. "true" new content) passes vale with a warning level configuration:

  • Change this to warning:

    nativelink/.vale.ini

    Line 5 in 5810489

    MinAlertLevel = error

  • Add a bogus obviously wrong word in any README to trigger a vale erorr on it.
  • When you now run pre-commit run -a it'll show you vale warnings. Ignore the warnings from generated and existing files, but make sure that no new warnings are introduced from the new content.

Reviewable status: 0 of 1 LGTMs obtained, and pending CI: pre-commit-checks

[MarcusSorealheis]

LFG B’Laké

Reviewable status: 1 of 1 LGTMs obtained, and pending CI: pre-commit-checks

[MarcusSorealheis]

Are the links working?

Reviewable status: 1 of 1 LGTMs obtained, and pending CI: Bazel Dev / ubuntu-22.04, Cargo Dev / macos-13, Cargo Dev / ubuntu-22.04, Installation / macos-13, Installation / macos-14, Installation / ubuntu-22.04, Publish image, Publish nativelink-worker-init, Publish nativelink-worker-lre-cc, Remote / large-ubuntu-22.04, asan / ubuntu-22.04, docker-compose-compiles-nativelink (20.04), docker-compose-compiles-nativelink (22.04), integration-tests (20.04), macos-13, pre-commit-checks, ubuntu-20.04 / stable, ubuntu-22.04, ubuntu-22.04 / stable, windows-2022 / stable

[blakehatch]

Yeah they are just splitting into a two PRs and doing a final pass with @aaronmondal rn. These will get in tonight

Reviewable status: 1 of 1 LGTMs obtained, and pending CI: Bazel Dev / ubuntu-22.04, Cargo Dev / macos-13, Cargo Dev / ubuntu-22.04, Installation / macos-13, Installation / macos-14, Installation / ubuntu-22.04, Local / ubuntu-22.04, Publish image, Publish nativelink-worker-init, Publish nativelink-worker-lre-cc, Remote / large-ubuntu-22.04, asan / ubuntu-22.04, docker-compose-compiles-nativelink (20.04), docker-compose-compiles-nativelink (22.04), integration-tests (20.04), integration-tests (22.04), macos-13, pre-commit-checks, ubuntu-20.04 / stable, ubuntu-22.04, ubuntu-22.04 / stable, windows-2022 / stable

[aaronmondal]

Reviewed 11 of 32 files at r1, 7 of 11 files at r2, 13 of 13 files at r3, 4 of 4 files at r4, all commit messages.
Reviewable status: 2 of 1 LGTMs obtained, and pending CI: Bazel Dev / ubuntu-22.04, Cargo Dev / macos-13, Cargo Dev / ubuntu-22.04, Installation / macos-13, Installation / macos-14, Installation / ubuntu-22.04, Local / ubuntu-22.04, Publish image, Publish nativelink-worker-init, Publish nativelink-worker-lre-cc, Remote / large-ubuntu-22.04, asan / ubuntu-22.04, docker-compose-compiles-nativelink (20.04), docker-compose-compiles-nativelink (22.04), integration-tests (20.04), integration-tests (22.04), macos-13, ubuntu-20.04 / stable, ubuntu-22.04, ubuntu-22.04 / stable, windows-2022 / stable