Skip to content

sphinx-quickstart: Enter should exit when existing conf.py is detected #75

@rowan-stein

Description

@rowan-stein

User Request

Bug: sphinx-quickstart with existing conf.py doesn't exit easily.

  • Running sphinx-quickstart in a folder with a conf.py already existing.
  • It says "Please enter a new root path name (or just Enter to exit)".
  • Pressing Enter returns an error: "Please enter a valid path name" (the prompt does not exit).

To Reproduce:

$ sphinx-quickstart
$ sphinx-quickstart

Expected behavior:

  • After pressing Enter, sphinx-quickstart exits.

Environment:

  • OS: Ubuntu 20.04
  • Python: 3.8.5
  • Sphinx: 3.2.1

Researcher Specification

Current behavior and root cause:

  • In sphinx/cmd/quickstart.py (interactive flow ask_user), when an existing conf.py is found in the selected root path (<root>/conf.py or <root>/source/conf.py), quickstart prints an error and prompts:
    • "Please enter a new root path (or just Enter to exit)"
  • The prompt uses do_prompt(..., default='', validator=is_path). An empty input is rejected by is_path('') with the message "Please enter a valid path name.", causing a loop. Therefore, pressing Enter never exits.

Expected behavior:

  • At the above prompt, pressing Enter should exit immediately with a non-zero status (exit code 1), without further prompting.
  • Suggested exit message: "Found existing conf.py — aborting."
  • Quiet mode (-q) behavior remains unchanged (return 1 if unsuitable path; no prompt).

Edge cases (left unchanged unless noted):

  • Detection remains limited to <root>/conf.py and <root>/source/conf.py.
  • Non-writable paths and non-Sphinx files are handled as today.
  • Symlinked conf.py is treated as existing.

Test plan:

  • Interactive: with <root>/conf.py present, run sphinx-quickstart, press Enter at the prompt → exit code 1; message includes error and abort text.
  • Interactive: with <root>/source/conf.py present → same.
  • Interactive: provide a valid new path → proceed to generate in the new path; no writes to original dir.
  • Quiet mode: sphinx-quickstart -q ... <root> with conf.py → exit code 1 and existing messages.

Implementation outline (no code):

  • In ask_user, change the prompt handling to accept empty input (Enter) and exit with code 1 when empty; otherwise, validate the provided path (directory) and continue.
  • Add or adjust tests in tests/test_quickstart.py to cover the above scenarios.

Acceptance criteria:

  • Interactive Enter exits with code 1 and prints abort message when conf.py exists.
  • Quiet mode unchanged.
  • Valid new path generation unaffected.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions