I'd like for this page to primarily be a listing of configuration options with data on each. The current version includes a lot of explanatory text outside of the options. I'd like to keep such content to a minimum.

A lot of the content here has been copied from the old server_howto doc. We need to be careful propagating that content as some of it could be inaccurate.

We've dropped a number of KRBV related options, and we should not document those.

Most of the config item headings here appear to be based on the example httpd file, e.g.

 DBName = koji

It's not 100% clear what the value after the = is meant to signify, but people are likely to assume this is the default, and many of the entries list the default incorrectly (e.g the dbname does not actually default to koji). I think we should be explicit and clearly the default value. Also, I think the heading should just be the name of the option with any other information on subsequent lines.

When I last looked at this, I ended up making a number of adjustments. That partial work is here:
https://pagure.io/fork/mikem/koji/commits/pr3098-updates

This probably needs a bit more cleanup. I keep switching back and forth about whether to include the Type field for the entries.

Side note -- I was curious how other projects format their configuration docs in sphinx. I found a number that use various sphinx extensions to provide .. confval:: markup, either by using the sphinx-toolbox package or simply including a similar extension in their conf.py file (sphinx itself does the latter for its own docs).

I'd rather not grow a dependency on sphinx-toolbox (doesn't seem to be in Fedora) and I'm not sure this is important enough to add custom code into conf.py, so I think the current approach of using .. glossary:: is fine.

@mikem Updated. I merged documentation part related to limit of names also.

I am for us it with type of field for entries :) .

works for me, let's run with it :thumbsup:

Commit 850bea59 fixes this pull-request