Thanks for filling these :since: annotations in!

After fixing the registry issue described below, this inexplicably fails on my machine with,

Exception occurred:
  File "/opt/exp/ghc/ghc-landing/docs/users_guide/flags.py", line 337, in generate_output
    env.app.builder)
AttributeError: 'NoneType' object has no attribute 'builder'

This fails on my machine with,

Exception occurred:
  File "/opt/exp/ghc/ghc-landing/docs/users_guide/flags.py", line 391, in setup
    app.registry.domains['std'].directives['ghc-flag'] = Flag
AttributeError: 'Sphinx' object has no attribute 'registry'

It looks like it should instead be,

app.add_directive_to_domain('std', 'ghc-flag', Flag)

There are enough "irreversible" flags that perhaps we want to allow the :reverse: field to be omitted.

While I love the fact that this allows us to build the users guide without building GHC, I am a bit weary of this falling out of date. I'll try to think about how we can fix this.

In 1.4.9 env.app has the comment "only set when update() is run." While in >1.6 it is set immediately.

Again, in 1.4.9 the entire registry module does not exist. This appears to have been added in 1.6.2.

As for using add_directive_to_domain(), it appears that the current version actually would work. That function checks that the given domain ('std') exists and checks that (because I passed a class and not an older format) I did not try to also provide other keyword arguements. It then runs the line I used.

I somewhat expected that Sphinx would not let me override an existing directive. The add_object_type() function creates a directive called ghc-flag as well, and I was replacing it with my own. But it does not appear to check if the directive already exists, so it would work in our case.

I'm fine with switching to the provided API, provided it works. However, I'm not sure which version would be more stable. The current version is perhaps overly direct, while the API version relies on an unchecked case that some may call a bug.

It in fact can be omitted. Only the :shortdesc: and :type: are mandatory.
When not provided, :reverse: defaults to the empty string, and :category: checks for a file default. If there is also no file default, an error is thrown to the effect of KeyError: <filename>.

The makeshift vim macro I whipped up to convert the old mkUserGuidePart data into this format was not smart enough to drop the :reverse: field when not needed.

The mkUserGuidePart code was mostly just formatting this nicely: https://downloads.haskell.org/~ghc/latest/docs/html/libraries/ghc-8.2.1/src/DynFlags.html#glasgowExtsFlags. While not the best presentation, it should at least be accurate.

I'm fine with switching to the provided API, provided it works. However, I'm not sure which version would be more stable. The current version is perhaps overly direct, while the API version relies on an unchecked case that some may call a bug.

It might be a good idea to bring this up with upstream, but keeping what you have here is fine with me

Ahh, I see. Perhaps it would be a easy to simply sed these empty :reverse: lines out of existence then?

Right, I'm fine keeping your approach for the time being, but ultimately it would be nice if the documentation were derived from the implementation. Otherwise the two will inevitably fall out of sync. Perhaps we could factor out glasgowExtsFlags (and the necessary flag types) into a separate module and compile a small utility to generate this list (which could be compiled with the stage0 compiler).

For the time being though I think what you have here is fine (although we should probably add a note next to glasgowExtsFlags to ensure that contributors update the documentation when they change it.