DOC: omit basic_units helper from gallery by LiJzd · Pull Request #31909 · matplotlib/matplotlib · GitHub
Skip to content

DOC: omit basic_units helper from gallery#31909

Open
LiJzd wants to merge 4 commits into
matplotlib:mainfrom
LiJzd:doc-ignore-basic-units-gallery
Open

DOC: omit basic_units helper from gallery#31909
LiJzd wants to merge 4 commits into
matplotlib:mainfrom
LiJzd:doc-ignore-basic-units-gallery

Conversation

@LiJzd

@LiJzd LiJzd commented Jun 16, 2026

Copy link
Copy Markdown

DOC: omit basic_units helper from gallery

PR summary

This PR prevents galleries/examples/units/basic_units.py from being rendered as a standalone gallery page. The file is a helper module used by the units examples, not a visual gallery example, and issue #17479 notes that it should likely be omitted from the gallery listing.

The file is still copied into the generated gallery output via copyfile_regex, so existing examples can continue to import it and users can still download it from links such as :download:\basic_units.py <basic_units.py>``.

Addresses one item from #17479.

AI Disclosure

I used Codex to inspect the issue, read the repository documentation, identify the smallest scoped change, and run local checks. I reviewed the resulting configuration change and verified the regex behavior locally.

PR checklist

  • "closes #0000" is in the body of the PR description to link the related issue
  • new and changed code is tested
  • [N/A] Plotting related features are demonstrated in an example
  • [N/A] New Features and API Changes are noted with a directive and release note
  • Documentation complies with general and docstring guidelines

Testing

  • git diff --check
  • python -m py_compile doc/conf.py
  • Local regex check confirming:
    • ../galleries/examples/units/basic_units.py matches ignore_pattern
    • ../galleries/examples/units/basic_units.py matches copyfile_regex
    • ordinary .rst files still match copyfile_regex
    • ordinary example .py files such as bar_unit_demo.py do not match either rule

Full documentation build was not run locally because this environment does not have Matplotlib's documentation dependencies installed, including sphinx_gallery.

@github-actions

Copy link
Copy Markdown

@github-actions github-actions Bot added the Documentation: examples files in galleries/examples label Jun 16, 2026
@github-actions github-actions Bot added the Documentation: user guide files in galleries/users_explain or doc/users label Jun 16, 2026

@story645 story645 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I broadly support this (thanks!) - I think this file is more confusing than helpful as a gallery example - but am confused about the notebook piece.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Why add this?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Thanks. The notebook is only there because once basic_units.py is ignored as a gallery example but still copied for the :download: links, Sphinx Gallery's all-notebooks zip step expected a matching basic_units.ipynb and the docs build failed without it.

I agree it is awkward. I can look for a cleaner Sphinx Gallery configuration that keeps basic_units.py available for the examples' download links without adding a placeholder notebook. The latest CircleCI docs build is green with this workaround.

@LiJzd

LiJzd commented Jun 22, 2026

Copy link
Copy Markdown
Author

@LiJzd LiJzd marked this pull request as ready for review June 22, 2026 04:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation: build building the docs Documentation: examples files in galleries/examples Documentation: user guide files in galleries/users_explain or doc/users first-contribution

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

2 participants