[all-commits] [llvm/llvm-project] 3cae8b: [lldb][docs] Add a doc page for enums and constants

[Raphael Isemann via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 3cae8b33297b14449514a87dcaa8996ba40db412
      https://github.com/llvm/llvm-project/commit/3cae8b33297b14449514a87dcaa8996ba40db412
  Author: Raphael Isemann <teemperor at gmail.com>
  Date:   2021-01-19 (Tue, 19 Jan 2021)

  Changed paths:
    M lldb/bindings/interface/SBLanguageRuntime.i
    M lldb/bindings/python/python.swig
    A lldb/docs/python_api_enums.rst

  Log Message:
  -----------
  [lldb][docs] Add a doc page for enums and constants

Enums and constants are currently missing in the new LLDB Python API docs.

In theory we could just let them be autogenerated like the SB API classes, but sadly the generated documentation
suffers from a bunch of problems. Most of these problems come from the way SWIG is representing enums, which is
done by translating every single enum case into its own constant. This has a bunch of nasty effects:

* Because SWIG throws away the enum types, we can't actually reference the enum type itself in the API. Also because automodapi is impossible to script, this can't be fixed in post (at least without running like sed over the output files).
* The lack of enum types also causes that every enum *case* has its own full doc page. Having a full doc page that just shows a single enum case is pointless and it really slows down sphinx.
* There is no SWIG code for the enums, so there is also no place to write documentation strings for them. Also there is no support for copying the doxygen strings (which would be in the wrong format, but better than nothing) for enums (let alone our defines), so we can't really document all this code.
* Because the enum cases are just forwards to the native lldb module (which we mock), automodapi actually takes the `Mock` docstrings and adds it to every single enum case.

I don't see any way to solve this via automodapi or SWIG. The most reasonable way to solve this is IMHO to write a simple Clang tool
that just parses our enum/constant headers and emits an *.rst file that we check in. This way we can do all the LLDB-specific enum case and constant
grouping that we need to make a readable documentation page.

As we're without any real documentation until I get around to write that tool, I wrote a doc page for the enums/constants as a stop gap measure.
Most of this is done by just grepping our enum header and then manually cleaning up all the artifacts and copying the few doc strings we have.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94959