Skip to content

[MNT]: Specify ordering in file in gallery folder #25032

Closed

Description

@story645

Since we wrote this extension to do the ordering, there's no reason we can't change it to read from README.txt in each directory. We could have it look for something that looks like a comment to reST so it does nothing in the sphinx-gallery-processed reST without having to do anything extra.
Originally posted by @QuLogic in #24746 (comment)

I think it's a relatively good first issue following #25028 because each readme can be parsed into its respective gallery list. Steps involved are

  1. figure out the reST comment notation that allows for easy specification of ordering + a consistent sentinel for placing unsorted files
  2. write a parser that translates the set of comments into a list that preserves the order (including sentinel)
  3. parse each file into its respective list in
    folder_lists = [examples_order, tutorials_order, plot_types_order]
  4. add documentation on doing this ordering to https://github.com/matplotlib/matplotlib/blob/main/doc/devel/documenting_mpl.rst?plain=1#L933

Medium difficulty because some familiarity with sphinx would be helpful, but not strictly necessary. I think a medium to advanced version of this would be implementing a .. gallery-toc custom directive

And yes, down the line we should maybe spin a maintain docs page off from the writing docs page.

An alternative to using the readme is using a special purpose 'gallery_order' file #24746 (comment)

Activity

  1. added
    🌱 Good first issueOpen a pull request against these issues if there are no active ones!
    Difficulty: Mediumhttps://matplotlib.org/devdocs/devel/contribute.html#good-first-issues
    on Jan 19, 2023
  2. jklymak commented on Jan 19, 2023

    @jklymak
    Member

    I was going to open a discussion with sphinx-gallery about this as well. It seems like something they should be able to handle.

  3. QuLogic commented on Jan 19, 2023

    @QuLogic
    Member

    I looked into this yesterday; it's not particularly difficult to implement, and I did about half of it. The subsection order is pretty easy to do as each one is independent, but the problem with the higher section order is that we currently have a mix with some special things appearing after the unsorted ones. I did not fully investigate if the ordering class gets access to all the directories but I don't believe so, so there's a little bit of extra work to handle the bookkeeping of the split there.

  4. changed the title [-][MNT]: Specify gallery ordering in readme[/-] [+][MNT]: Specify ordering in file in gallery folder[/+] on Jan 21, 2023
  5. Higgs32584 commented on Mar 10, 2023

    @Higgs32584
    Contributor

    I want to do this issue, but I am a little bit confused by this part:
    write a parser that translates the set of comments into a list that preserves the order (including sentinel)

    Are you pulling the text from each README.md or reordering the directory? Thank you!

  6. added a commit that references this issue on Mar 29, 2024
    eb8c12a
  7. Kruthikakatta commented on Dec 20, 2025

    @Kruthikakatta

    I’d like to work on this issue.

  8. timhoffm commented on Dec 20, 2025

    @timhoffm
    Member

    @story645 Is this still needed / worth the effort?

    Given the constrains of sphinx-gallery due to their ordering logic, https://github.com/matplotlib/matplotlib/blob/main/doc/sphinxext/gallery_order.py isn't too bad.

    We have a declarative order specification in there. Given that changes to the gallery order are are, an order file in the gallery doesn't seem to bring much additional benefit. And I'm reluctant to add more complex logic that we'd have to maintain.

  9. story645 commented on Dec 22, 2025

    @story645
    MemberAuthor

    Given that changes to the gallery order are are, an order file in the gallery doesn't seem to bring much additional benefit.

    Yeah, I'm fine closing this and maybe repopening if there's a change to the docs where it'd be really useful to order by file and can't just use the sphinx minigallery command to do it.

  10. parthivdholiya77-coder commented on Jan 28, 2026

    @parthivdholiya77-coder

    Hi, I am new to open source and would like to work on this issue.
    Can you please guide me on where to start?

  11. timhoffm commented on Jan 28, 2026

    @timhoffm
    Member

    This is closed. No action planned.

  12. removed
    🌱 Good first issueOpen a pull request against these issues if there are no active ones!
    on Mar 19, 2026
  13. added this to the v3.11.0 milestone on Jun 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions