Is your feature request related to a problem? Please describe.

Sphinx's conf.py template duplicates contents from Sphinx's documentation, which results in redundancy and does not provide any context for potential additional configuration values. The documentation comments also add additional length to the configuration file; making it seem more complex than it actually is.

More importantly, users do not add such comments for configuration values they add or modify, which means that the configuration file ends up with a mix of values-with-comments-describing-them and those without. This makes the configuration file difficult to navigate and to locate the relevant configuration within it.

It also allows for inconsistency between the documentation and the conf.py template to creep in unnoticed. Right now, for example, language is in the "General configuration" section in the conf.py template. However, it is not under the "General configuration" header in the documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration. Instead, it is under the "Options for internationalization" section: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization. I wouldn't be surprised if some of the comments in the conf.py file are outdated or missing information that's included in the corresponding documentation page.

Describe the solution you'd like

• Drop the comments from the configuration file template, that duplicate the documentation for each of the options or provide example usage of the options.
• Add links to each of the "sections" in the configuration file, that correspond to the relevant documentation section.

This has quite a few benefits IMO:

• it helps improve discoverability of not-in-the-file configuration options.
• it makes it easier to get to the "proper" documentation of the options.
• it makes the configuration file more maintainable, by reducing redundancy added by the comments.
• it makes the configuration file less "complicated" ¹.
• it makes it easier to keep the configuration file in sync with the documentation (language example above).
• it clearly communicates to documentation authors how to maintain this file (make a section and put the documentation URL in the next line, or add to the existing section).
• it nudges extension authors to publish similar configuration listing pages, since that's an expectation set by the overall style of the configuration file.

Describe alternatives you've considered

• Maintaining status quo.

  This is the path of least effort. I don't think this is a good idea though, because we will continue to push for the mixed-comment + seeming-more-complicated-than-it-actually-is configuration files.

• Not including the URLs, only dropping comments

  This would reduce the percieved complexity of the file, as well as the length of it. I think it's still a worthwhile improvement, but we'd lose the discoverability benefits of having a URL immediately accessible.

Additional context

Example configuration file, that incorporates all the suggestions: https://github.com/pradyunsg/installer/blob/48f44b87eb438bc32ecad27c29b5d90fa03f2a37/docs/conf.py
Example configuration file, that drops the comments and does NOT include URLs: https://github.com/pypa/pip/blob/7f8a6844037fb7255cfd0d34ff8e8cf44f2598d4/docs/html/conf.py

FWIW, I think having a "Options for internationalization" section in the conf.py file when language is set, would help make it clearer that the Sphinx supports it out-of-the-box.