Potential improvements to sphinx-quickstart's default conf.py_t template

[pradyunsg]

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.

Footnotes

1. In addition to the reduction of length, I think the comments are usually a subtle indicator that there's some sort of complexity/subtly -- they usually serve to provide context that might not be obvious to the reader. Most options in Sphinx's configuration file are not subtle in that way, and even if they are, the details of how they interact in the context of a single documentation set should be more important than the fact that the verbatim information about how they behave (i.e. let the documentation authors add comments about the things they care about). ↩

[kapooramit]

Makes complete sense. Reduced clutter is a welcome change.

[webknjaz]

FWIW I like having the URLs + sections in a deterministic order because it makes it easier to sync this config file across projects while minimizing the merge conflicts in the process.

[tk0miya]

+1 for "Not including the URLs, only dropping comments".
+0 for the proposal.

FYI: Now the default conf.py has a URL for the reference on the top.
https://github.com/sphinx-doc/sphinx/blob/4.x/sphinx/templates/quickstart/conf.py_t#L5

[pradyunsg]

@tk0miya Would you be willing to elaborate on why you seem to prefer not including URLs?

I think the following two advantages that are afforded by doing that are significant IMO:

• 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.

---

FYI: Now the default conf.py has a URL for the reference on the top.

That page lists all of Sphinx's "base" configuration variables... which (1) is a long list and (2) aren't the only configuration variables that might be set in a specific documentation set's configuration file -- many are provided by Sphinx extensions; sometimes with names that don't make it immediately clear where they are coming from.

Further, having a link to the specific heading would also serve as a more direct way to access the relevant variables' documentation. As an example, take project information options, options for internationalisation, autodoc configuration variables and sphinx-tabs configuration variables -- they're all in different parts of different websites and, yet, if the URL is included in the section header, reaching them will consistently only take a single cmd/ctrl+click on most modern GUI text editors or a copy-line-and-paste-in-browser in other situations.

[pradyunsg]

I've filed #10571 based on the discussion here. I've targetted 5.x based on the milestone this issue has.