Add reference docs for BUILD file symbols

[huonw]

This adds a new section to the reference docs: /2.x/reference/build-file-symbols/. This renders all the known non-target BUILD file symbols, as indicated by the name_to_build_file_info key of the help-all output JSON.

This JSON looks like the following, and this generation basically just mashes it up into documentation form:

  "name_to_build_file_info": {
    "PANTS_VERSION": {
      "documentation": null,
      "is_target": false,
      "name": "PANTS_VERSION",
      "signature": null
    },
    "__defaults__": {
      "documentation": "Provide default field values.\n\nLearn more https://www.pantsbuild.org/2.22/docs/using-pants/key-concepts/targets-and-build-files#field-default-values",
      "is_target": false,
      "name": "__defaults__",
      "signature": "(*args: 'SetDefaultsT', ignore_unknown_fields: 'bool' = False, ignore_unknown_targets: 'bool' = False, **kwargs) -> 'None'"
    },
    "__dependencies_rules__": {
      "documentation": "Declare dependencies rules.",
      "is_target": false,
      "name": "__dependencies_rules__",
      "signature": "(*args, **kwargs) -> 'None'"
    },
    "__dependents_rules__": {
      "documentation": "Declare dependents rules.",
      "is_target": false,
      "name": "__dependents_rules__",
      "signature": "(*args, **kwargs) -> 'None'"
    },
    "_generator_sources_helper": {
      "documentation": null,
      "is_target": true,
      "name": "_generator_sources_helper",
      "signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
    },
    "_lockfile": {
      "documentation": null,
      "is_target": true,
      "name": "_lockfile",
      "signature": "(**kwargs: 'Any') -> 'TargetAdaptor'"
    },
...

This is a new sidebar option:

Some of these have reasonable docs:

Others do not have good docs:

I think we should land this and then separately work to improve the documentation of each BUILD file symbol:

• Include "provider" value for BUILD file symbols in help-all output pants#20976
• stevedore_namespace documentation shows str's doc string pants#20977
• PANTS_VERSION BUILD file symbol has no docs pants#20978
• JVM BUILD file symbol help text isn't shown in help/help-all pants#20979
• per_platform help text shows plugin-focused guide, not usage pants#20980

To make this work, there's two other changes required, which are done as separate commits:

• support for back-tick code blocks, to avoid mangling them
• explicit sidebar positions, so that BUILD file symbols is placed last, rather than before Global options (thus becoming the default)

This generates back to the first version that include that (2.16) and involves some other changes to the code-genned docs, hence this is targeted automation:sync-docs.

Fixes #212

[kaos]

Awesome. 🚀

[thejcannon]

Amazing work!

[thejcannon]

Ah yeah that's a bummer. FWIW we delayed publishing these docs solely because we threw the baby out with the bathwater on documenting constants.

Thank you for doing this, and for not allowing constants to halt a great improvement 👍👍

[huonw]

Ah, do you have a reference to any of that? Just want to make sure I'm across any extra issues that were identified to avoid having to rediscover everything.

[thejcannon]

I think this is what I'm thinking of: pantsbuild/pants#18117

[huonw]

Ah cool, thanks. That seems to have some good thinking, particularly relevant to pantsbuild/pants#20978, but none of it seems like major missing pieces that should block this... so I'll get it in.

[huonw]

Filed:

• Include "provider" value for BUILD file symbols in help-all output pants#20976
• stevedore_namespace documentation shows str's doc string pants#20977
• PANTS_VERSION BUILD file symbol has no docs pants#20978
• JVM BUILD file symbol help text isn't shown in help/help-all pants#20979
• per_platform help text shows plugin-focused guide, not usage pants#20980