Skip to content

Conversation

@int-arsh
Copy link

Description

Closes #4967

This PR consolidates scattered Jupyter Notebook documentation into a comprehensive, dedicated page at docs/usage_and_configuration/jupyter_notebooks.md.

Problem: Currently, Jupyter-related information is scattered across multiple documentation files (README.md, getting_started.md, FAQ, source_version_control.md), making it difficult for users to find complete information about using Black with Jupyter Notebooks.

Solution: Created a single authoritative page that covers:

  • Installation with pip install "black[jupyter]"
  • Basic usage and command-line examples
  • How Black formats notebooks (what's preserved, what's changed)
  • Cells that won't be formatted (automagics, cell magics, etc.)
  • Configuration options (--python-cell-magics, --skip-magic-trailing-comma)
  • Pre-commit integration with black-jupyter hook
  • Editor integration references
  • Troubleshooting common issues

Testing: Documentation builds successfully with strict mode:

sphinx-build -a -b html -W docs/ docs/_build/

Checklist - did you ...

  • Implement any code style changes under the --preview style, following the stability policy?
    • N/A - This is a documentation-only change
  • Add an entry in CHANGES.md if necessary?
    • N/A - Documentation changes don't require changelog entries
  • Add / update tests if necessary?
    • N/A - Documentation verified via sphinx-build -W
  • Add new / update outdated documentation?
    • Yes - Created comprehensive Jupyter documentation page

Closes psf#4967

- Created dedicated jupyter_notebooks.md page consolidating all Jupyter info
- Added to usage_and_configuration navigation
- Covers installation, usage, configuration, pre-commit, and troubleshooting
- Documentation builds successfully with strict mode (-W flag)"
@int-arsh
Copy link
Author

@cobaltt7
This is a documentation-only change, so a changelog entry isn’t required.

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.

Docs: Better documentation for Jupyter usage

1 participant