Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reduce content in the sphinx-quickstart conf.py file #10571

Merged
merged 4 commits into from Jun 25, 2022

Conversation

pradyunsg
Copy link
Contributor

Subject: (see pull request title)

Feature or Bugfix

  • Feature
  • Bugfix
  • Refactoring

Purpose

Simplify the sphinx-quickstart conf.py file, reducing the percieved complexity of the conf.py file generated by default.

Detail

  • Dropping comments about configuration fields
  • Dropping commented code generation
  • Ensure the file always has a trailing newline
  • Consistent newline separation of various sections
  • Include URLs to the relevant documentation pages listing all configuration variables

Relates

Closes #10056

This makes the file be simpler whenever possible, reducing the amount of
explanation and commented behaviour provided in the `conf.py` file
generated by `sphinx-quickstart`.
@pradyunsg
Copy link
Contributor Author

For comparing the difference in the output files generated by this, here's an example based on running:

$ sphinx-quickstart /tmp/dev1 -p test -l en -a test --sep -r 1.0 -v 1.0 --ext-intersphinx --ext-todo
$ cat /tmp/dev1/source/conf.py

Before this PR:

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'test'
copyright = '2022, test'
author = 'test'

# The short X.Y version
version = '1.0'

# The full version, including alpha/beta/rc tags
release = '1.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']


# -- Extension configuration -------------------------------------------------

# -- Options for intersphinx extension ---------------------------------------

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

# -- Options for todo extension ----------------------------------------------

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

(no trailing newline)

After this PR:

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'test'
copyright = '2022, test'
author = 'test'

version = '1.0'
release = '1.0'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
]

templates_path = ['_templates']
exclude_patterns = []

language = 'en'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

# -- Options for intersphinx extension ---------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

# -- Options for todo extension ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

todo_include_todos = True

Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

{% else -%}
# import os
# import sys
{% if module_path -%}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: Bothappend_syspath and module_path are available on apidoc. And quickstart does not passes both of them. So this if-condition is not needed.

Copy link
Contributor

@humitos humitos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯

@AA-Turner
Copy link
Member

This will need a CHANGES entry but looks reasonable1 apart from that. @pradyunsg please can you add one?

A

Footnotes

  1. I could argue over the stylistic choice of the very long dashes line or URL inclusion, but the improvement overall is bigger than those two points, so I won't!

@AA-Turner AA-Turner modified the milestones: 5.x, 5.1.0 Jun 22, 2022
@AA-Turner AA-Turner added type:enhancement enhance or introduce a new feature and removed type:proposal a feature suggestion labels Jun 22, 2022
@humitos
Copy link
Contributor

humitos commented Jun 23, 2022

@AA-Turner

I could argue over the stylistic choice of the very long dashes line

I don't like them either, but I guess these weren't touched to reduce the friction/amount of changes of the PR and be able to merge faster 😄

@pradyunsg
Copy link
Contributor Author

Precisely. :)

pradyunsg added a commit to pradyunsg/sphinx that referenced this pull request Jun 24, 2022
@pradyunsg
Copy link
Contributor Author

@AA-Turner Added the CHANGES entry. :)

pradyunsg added a commit to pradyunsg/sphinx that referenced this pull request Jun 24, 2022
CHANGES Outdated Show resolved Hide resolved
CHANGES Outdated Show resolved Hide resolved
@AA-Turner AA-Turner merged commit 8525343 into sphinx-doc:5.x Jun 25, 2022
@AA-Turner
Copy link
Member

Thanks @pradyunsg!

A

@pradyunsg pradyunsg deleted the change-conf-py-template branch June 25, 2022 15:12
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 26, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
api:cmdline internals:config type:enhancement enhance or introduce a new feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

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