[Nexthop] Improve PlatformManager and platform configuration documentation

[marif-nexthop]

Pre-submission checklist

• I've ran the linters locally and fixed lint errors related to the files I modified in this PR. You can install the linters by running pip install -r requirements-dev.txt && pre-commit install
• pre-commit run

Summary

PlatformManager is a core component of FBOSS platform software responsible for hardware discovery and device management. This PR improves the documentation by adding more information about PlatformManager and platform configuration.

• Create PlatformManager category (sidebar menu)
• Split platform_manager.md into overview.md and modeling.md
• Added total nine pages covering information about PlatformManager and platform configuration

Test Plan

Viewed in a local docusaurus instance.

[Scott8440]

I really appreciate all the work put into this documentation, but most of this feels unnecessary. In general we want to keep documentation as close to the code that it describes as possible. Most of the time this means comments in .thrift files.

I would also love to see some of this documentation effort put into improving the --help messages. There are several parts here which would fit nicely there.

There are a couple of pieces here which I do think are valuable, and I mentioned where we should move them.

[Scott8440]

I feel like this should be handled by platform_manager --help. Any documentation here feels redundant and prone to becoming outdated if we make any changes to the CLI interface

[Scott8440]

I believe documentation here fits better as comments in the thrift service definition itself.

[Scott8440]

An explanation of presence detection as a feature is useful, but I feel the amount of documentation here is too much. Perhaps this would fit better in a "Features" section of the existing platform_manager.md

Just explain the basics of what this provides and enables. Details about actual config implementation should be left to the thrift file or the sample config.

[Scott8440]

Since kmods.json is a requirement of the BSP, documentation of that should stay there.

Other pieces of the documentation here should be provided by --help

Details about what exactly happens during the package management step feels too detailed to be in documentation.

[Scott8440]

See the existing platform_manager.md doc which provides a high-level overview

[travisb-nexthop]

Please note that this PR splits the previous platform_manager.md into overview.md and modeling.md in order to create space in the structure for the additions. This high-level overview mostly is from platform_manager.md.

See b3319ae where this split is performed.

[Scott8440]

Overview of exploration flow is valuable. If it doesn't already exist in platform_manager.md I would add that there.

Details of the status and error enums feels redundant/obvious.

[Scott8440]

These conventions (except for "be descriptive") should be codified in ConfigValidator instead of a doc.

[Scott8440]

Since block configs are probably the most confusing part of the configs it makes sense to have some documentation on them, but if i remember correctly there's already some pretty good documenation in the thrift file itself.

Examples should be put into the sample config instead of a doc.

[meta-codesync]

@Scott8440 has imported this pull request. If you are a Meta employee, you can view this in D98980604.

[meta-codesync]

@Scott8440 merged this pull request in 6c15fbc.