sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Expose interface for changing `html_theme` in `quickstart`'s `conf.py` template when auto-generating #11560

Open vkottler opened 1 year ago

vkottler commented 1 year ago

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

With sphinx-apidoc, it's possible to generate a conf.py with the -F, --full option.

There are some command-line options for controlling data that is passed to the conf.py template.

It's not possible to change the theme because it's hard-coded in the template:

html_theme = 'alabaster'

This is one of the most impactful configuration options and shouldn't require user-provided templates just to change that to something else.

Describe the solution you'd like

Use alabaster as a default when rendering the template, but expose a command-line option (for e.g. sphinx-apidoc) or an interactive prompt for sphinx-quickstart to set the theme.

Describe alternatives you've considered

Expose a simpler, non-code configuration interface some other way. It seems like there's discussion about this in some other issues:

Additional context

Here is the template I use and how I'm invoking the command-line tools.

It's possible to use sphinx-apidoc and sphinx-build for a truly zero-configuration documentation-generation experience, except for being able to set the theme (in my case, sphinx_book_theme).

picnixz commented 1 year ago

+1 because I'm usually usiung sphinx-rtd-theme for deployment and I prefer its layout over alabaster. I think it's a reasonable feature.