DOC: Add axis sharing section to subplot_mosaic guide#31720
Conversation
|
The docs-python3 CI failure appears to be a pre-existing infrastructure issue — the build fails at requirements/dev/build-requirements.txt not found, before it reaches any documentation content. This is unrelated to my changes. |
|
⏰ This pull request might be automatically closed in two weeks from now. Thank you for your contribution to Matplotlib and for the effort you have put into this PR. This pull request does not yet meet the quality and clarity standards needed for an effective review. Project maintainers have limited time for code reviews, and our goal is to prioritize well-prepared contributions to keep Matplotlib maintainable. Matplotlib maintainers cannot provide one-to-one guidance on this PR. However, if you ask focused, well-researched questions, a community member may be willing to help. 💬 To increase the chance of a productive review:
As the author, you are responsible for driving this PR, which entails doing necessary background research as well as presenting its context and your thought process. If you are a new contributor, or do not know how to fulfill these requirements, we recommend that you familiarize yourself with Matplotlib's development conventions or engage with the community via our Discourse or one of our meetings before submitting code. If you substantially improve this PR within two weeks, leave a comment and a team member may remove the |
|
Hi, thanks for the PR but please fill out the PR template correctly, including the AI disclosure. |
Summary
Adds a new "Axis sharing" section to the subplot_mosaic user guide (galleries/users_explain/axes/mosaic.py), as requested in #31699 (extracted from #25417).
What was the problem?
The existing subplot_mosaic documentation had no guidance on using sharex and sharey parameters. Users encountering unexpected behavior — particularly when combining axis sharing with empty sentinels — had no reference to understand why tick labels disappeared or how to fix it.
What this PR adds
Demonstrates fig.subplot_mosaic("AC;BC", sharex=True) to show the standard sharing behavior where only the bottom row displays x-axis tick labels.
Demonstrates fig.subplot_mosaic(".A;BC", sharey=True) where the top-left cell is an empty sentinel.
Explains that because the leftmost Axes in the top row is blank, axis sharing removes the y-tick labels from all remaining Axes in that row, leaving no visible labels — which is usually not the intended result.
Shows how to manually re-enable tick labels using axd["B"].tick_params(labelleft=True), giving users a clear and simple fix.
How to verify
Run the mosaic example script:
python galleries/users_explain/axes/mosaic.py
The three new figures should render without errors:
A shared-x mosaic with tick labels only on the bottom row.
The empty sentinel + sharey case with missing tick labels on the top row.
The same layout with the tick_params fix applied, restoring the tick labels.
Closes #31699