Add optional description argument to app.add_config_value

[chrisjsewell]

Sphinx (+ extensions) has a lot of available configuration variables (>200),
which can make it not so user-friendly to write the conf.py,
whilst trying to remember them all or search for them on the sphinx/extension websites 😅

Allowing for the co-location of a short description on the configuration value,
can be utilised by external tools, like LSPs to provide better sphinx authoring support
(things like hover descriptions of variables in the conf.py)

---

Note, I already have auto-completion working 😄

[picnixz]

Oh... this can be very useful though I don't know if there's a PyCharm plugin for that. But if it can help people, I think it should be fine?

I assume that you want to add description to the built-in configuration values in a separate PR?

[chrisjsewell]

I don't know if there's a PyCharm plugin for that

making a language server, that can work in most editors 😉

I assume that you want to add description to the built-in configuration values in a separate PR?

yep 👍, didn't want to go to the trouble for the API was agreed on

---

the only other thing I was thinking is if there could be some sort of category/categories option, to allow easier identification as to the origin of the config, e.g. app.add_config_value(..., categories=["my_extension", "html"])
don't know if you have any thought?

[picnixz]

app.add_config_value(..., categories=["my_extension", "html"])

I think it would be an overkill here. I would be happy to write a short description, but most of the time, I expect extension developers not to bother about the categories. Ideally, we could get the frame that called add_config_value automatically and add it internally and it would become easier (at least, we can have the defining module, maybe not the builder for which it was meant to).

I think it's preferrable to correctly name the configuration values rather than add 'categories' like this (for description, I see a reason for IDEs).