[chore] Remove docfx as unnecessary

[lmolkova]

Fixes #987

Changes

Docfx was introduced in the spec repo a while ago - open-telemetry/opentelemetry-specification#742
with the intention to detect broken links.

Docfx v3 we used since open-telemetry/opentelemetry-specification#2285 was in preview and is no longer accessible and not recommended to be used even if built from sources.

Docfx is a site-generator, not a linting tool, there is no (?) documentation on checks against docs it does.

We already have individual markdown lint and link checks.

With all of this I suggest removing docfx since it seems to be unnecessary.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]

PS: I'll send a similar PR to the spec.

[lmolkova]

/cc @reyang in case you have any context on docfx checks we might still need

[reyang]

/cc @reyang in case you have any context on docfx checks we might still need

IIRC, relative links in markdown is verified by docfx, probably something that can be covered or already covered by markdownlint.

[lmolkova]

IIRC, relative links in markdown is verified by docfx, probably something that can be covered or already covered by markdownlint.

thanks! let me check

[lmolkova]

thanks @reyang for the pointer, neither markdownlint nor markdown-link-check check fragment part in a different file ([see foo](./bar#baz)) and there seem to be no other common checker for it.
I'll try to resurrect docfx v2 then

[reyang]

FYI - https://github.com/theoludwig/markdownlint-rule-relative-links seems promising (although the download number seems low). Probably give it a try as it seems to be blessed by the owner of markdownlint DavidAnson/markdownlint#586 (comment).

[lmolkova]

you sent me to the rabbit hole @reyang 😅

apparently markdownlint-rule-relative-links does not support absolute links (e.g. /docs/http/http-spans.md#something). It does support validation for ./docs/http/http-spans.md#something.
If my JavaScript was any good, I'd consider contributing something.

The TL;DR:

docfx v2 does not support checking anchors in other files (only within the same file), which is already covered by markdownlint.

I'll merge this PR and will create an issue to figure out how to do cross-file anchor checks.

[trask]

thanks @reyang for the pointer, neither markdownlint nor markdown-link-check check fragment part in a different file ([see foo](./bar#baz)) and there seem to be no other common checker for it. I'll try to resurrect docfx v2 then

in Java, we're pinning an older version of markdown-link-check (v3.11.2) before anchor link checking broke, looks like a couple other otel repos have linked to that markdown-link-check issue too 😅

[lmolkova]

thanks @reyang for the pointer, neither markdownlint nor markdown-link-check check fragment part in a different file ([see foo](./bar#baz)) and there seem to be no other common checker for it. I'll try to resurrect docfx v2 then

in Java, we're pinning an older version of markdown-link-check (v3.11.2) before anchor link checking broke, looks like a couple other otel repos have linked to that markdown-link-check issue too 😅

cool, I'll check and send the PR - I have some other changes for that thing staged.

[lmolkova]

@trask I checked, it's a slightly different problem. The thing we're missing is #1009 and markdown-link-check never supported it :(

[trask]

oh no, I thought we (Java) were getting cross-file anchor link checking, but did a quick test and we're not 😢