feat: add Fabricator API reference

[pau-hedgehog]

No description provided.

[github-actions]

🚀 Deployed on https://preview-106--hedgehog-docs.netlify.app

[qmonnet]

I note that this is a draft, but here are some preliminary comments anyway:

• It would be great to mention where the source for the doc is (https://github.com/githedgehog/fabricator/blob/master/docs/api.md?plain=1), for those dataplane engineers who aren't so familiar with the fabric and fabricator code 🙂
• Do you think you could run locally with the changes from https://github.com/githedgehog/docs/pull/95/files, to see if the new API reference introduces broken links? We don't necessarily have to fix them all before merging this PR, but I'm curious to see if there will be any.
• This new reference is a candidate for automation, similar to what we try to do in ci: Add workflow to automate API reference sync on new version tags fabric#822.

[pau-hedgehog]

• Do you think you could run locally with the changes from https://github.com/githedgehog/docs/pull/95/files, to see if the new API reference introduces broken links? We don't necessarily have to fix them all before merging this PR, but I'm curious to see if there will be any.

pau@pau-TP-P14s:~/docs$ just build --strict
docker run -q --pull=always --rm -v $(pwd):/docs -p 8000:8000 ghcr.io/githedgehog/hhdocs:20241202 mkdocs build --strict
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /docs/site
WARNING -  Doc file 'install-upgrade/config.md' contains an absolute link '/reference/fab-api/', it was left as is. Did you mean '../reference/fab-api.md'?
WARNING -  Doc file 'reference/api.md' contains a link '#map[string]switchstatebgpneighbor', but there is no such anchor on this page.
WARNING -  Doc file 'reference/api.md' contains a link '#map[string]vpcpeer', but there is no such anchor on this page.
WARNING -  Doc file 'reference/api.md' contains a link '#nostype', but there is no such anchor on this page.
WARNING -  Doc file 'reference/api.md' contains a link '#redundancytype', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#prefix', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#addr', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#prefixordhcp', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#fabricmode', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#alloyconfig', but there is no such anchor on this page.
WARNING -  Doc file 'reference/fab-api.md' contains a link '#version', but there is no such anchor on this page.

Aborted with 11 warnings in strict mode!
error: Recipe `_run` failed on line 14 with exit code 1

What do you suggest we do about all these @qmonnet ?

[qmonnet]

Well I'd like to fix them one way or another, to avoid broken links in the docs 😅. But I'm not sure what's the best way to fix them. The map[...] ones should be easy enough to address by post-processing the file, but the other ones are on a case-by-case basis, and that's not great. I suppose there's a way to reorganise the code that we generate this from in such a way that we can get better links, but I'm not familiar enough with it to see how exactly

[qmonnet]

Related - githedgehog/fabric#809

I could fix some links by exposing more code when generating the API ref, for example, but this pulled some definitions that we don't want to appear in the doc. I guess that by refactoring in a way where we can expose the desired types, but not the rest, we should be able to fix the links. I've got githedgehog/fabric#830 next to make sure we don't break links again after that.

[pau-hedgehog]

WARNING - Doc file 'install-upgrade/config.md' contains an absolute link '/reference/fab-api/', it was left as is. Did you mean '../reference/fab-api.md'?

For now I will fix the following, which is the only one I'm in control of:

WARNING -  Doc file 'install-upgrade/config.md' contains an absolute link '/reference/fab-api/', it was left as is. Did you mean '../reference/fab-api.md'?