docs: don't remove freeform sub-options

[MattSturgeon]

This isn't a fully correct fix, but it's much closer to the intended behaviour.

FIXME: We incorrectly remove _freeformOptions here.

However we can't fix the bug because we derive page names from attrnames;
the correct behaviour would be to ignore attrnames and use option locs.

As a workaround, merge the freeform options at the top of these attrs,
however this can run into name conflicts 😢

We should move this workaround to where we decide the page name and
whether to nest into a sub-page, so that we can keep the original
_freeformOptions attr as intended.

From #3243:

I've noticed that the freeformtype's suboptions don't seem to get documented. I haven't checked yet if this is an issue with submodule, freeformtype, or our docs impl.

It's an issue with our hand-rolled docs.

Submodules with a freeformType return the freeformType's sub-options in a _freeformOptions attr. We remove that here.

The reason we do that is because our current docs impl uses attr names to determine page-names, however it is intended that attr names be ignored when rendering docs and only option loc paths be used. Therefore options.lsp.servers.type.getSubOptions options.lsp.servers.loc)._freeformOptions.enable should render with as lsp.servers.<name>.enable not as lsp.servers._freeformOptions_.enable:

nix-repl> (c.options.lsp.servers.type.getSubOptions c.options.lsp.servers.loc)._freeformOptions
{
  _module = { ... };
  activate = { ... };
  config = { ... };
  enable = { ... };
  name = { ... };
  package = { ... };
}

nix-repl> inputs.nixpkgs.lib.showOption (c.options.lsp.servers.type.getSubOptions c.options.lsp.servers.loc)._freeformOptions.enable.loc
"lsp.servers.<name>.enable"

Note that when NixOS renders option docs (and also how we do it in the beta-docs PR), all options are recursively collected into a list, so the attr names are discarded and the option's loc is all that remains.

[mergify]

This pull request, with head sha 9caeb51238748d885a91562e753d41b74155ff59, has been successfully merged with fast-forward by Mergify.

This pull request will be automatically closed by GitHub.

As soon as GitHub detects that the sha 9caeb51238748d885a91562e753d41b74155ff59 is part of the main branch, it will mark this pull request as merged.

It is possible for this pull request to remain open if this detection does not happen, this usually happens when a force-push is done on this branch docs-freeform-subopts, this means GitHub will fail to detect the merge.