Skip to content

Document explicit extraction mapping file selection - #1345

Open
xuu33030 wants to merge 1 commit into
python-babel:masterfrom
xuu33030:docs/1063-explicit-mapping
Open

xuu33030 wants to merge 1 commit into
python-babel:masterfrom
xuu33030:docs/1063-explicit-mapping

Conversation

@xuu33030

Copy link
Copy Markdown

Summary

The mapping documentation describes INI and TOML syntax, but does not show how to select a configuration file. This leaves readers unsure whether a particular filename is required or whether pyproject.toml is loaded automatically.

  • Show pybabel extract -F examples for babel.cfg, babel.toml, and pyproject.toml.
  • Explain explicit selection, the default Python-only mapping, and filename-based TOML/INI handling.
  • Correct the introduction to include the built-in JavaScript extractor.

The existing sections already describe built-in extractors, common options, and TOML syntax; this fills the remaining invocation gap. No runtime behavior changes.

Closes #1063.

Validation

On macOS with CPython 3.13.5, after importing the repository's CLDR 48.2 data:

  • python -m pytest -q tests: 6502 passed, 1174 skipped, 1 xfailed. Skips include unavailable pytz, setuptools, and benchmark dependencies, plus platform/deprecation-specific cases. One existing pytest parametrization deprecation warning.
  • python -m pytest -q tests/messages: 383 passed, 1 skipped.
  • Extracted the three new CLI commands and corresponding INI/TOML examples directly from the documentation, then ran them against temporary Python and JavaScript files. Verified the resulting POT messages. Also verified that a pyproject.toml ignore mapping has no effect without -F and takes effect when explicitly selected. These were local behavioral checks, not new committed tests.
  • git diff --check: passed.
  • python -m sphinx -b html -W --keep-going docs <output>: not clean on either the unchanged base or this branch. Both report the same five existing diagnostics (JavaScript extractor docstring indentation and unresolved links in dates/dev/messages); no new diagnostic was introduced.

The full multi-version/platform CI matrix was not run locally.

AI assistance disclosure: this documentation change and local verification were prepared with Hermes Agent assistance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

doc: Missing documentation on configuration

1 participant