Skip to content

Make downloading pre-built PDF docs easier #31173

Description

@SuperCowProducts

The instructions for building PDF from source repo are difficult to follow and fail: I eventually found https://matplotlib.org/stable/Matplotlib.pdf, but could we make this clearer on the website? I feel like it should be on the homepage (https://matplotlib.org/) so that someone who needs to learn can just instantly access it.

Activity

  1. story645 commented on Feb 18, 2026

    @story645
    Member

    Which instructions were you trying to follow?
    Would adding a link to https://matplotlib.org/devdocs/devel/document.html#build-the-docs from https://matplotlib.org/stable/install/index.html#install-source work or do you think it needs to be more detailed? If so, what sorts of things should be documented and where specifically?

  2. timhoffm commented on Feb 18, 2026

    @timhoffm
    Member

    If I understand correctly, the request is rather to have a link the pdf on there website.

  3. story645 commented on Feb 18, 2026

    @story645
    Member

    Then doesn't this issue belong on the matplotlib.org repo? B/c it'd be a change to the html there given we apparently already build it if @SuperCowProducts found a link?

    ETA: I guess there used to be a link near versions and we could maybe bring something like that back? ETA2: maybe under the cheat sheets?

  4. SuperCowProducts commented on Feb 18, 2026

    @SuperCowProducts
    Author

    That sounds like a good idea actually. Thanks for the links also!

  5. timhoffm commented on Feb 19, 2026

    @timhoffm
    Member

    Alternative would be a section "PDF documentation" below https://matplotlib.org/devdocs/index.html#about-us.

  6. SuperCowProducts commented on Feb 19, 2026

    @SuperCowProducts
    Author

    Yeah, somewhere near the cheatsheet pdfs should make sense

  7. Farzah11 commented on Feb 20, 2026

    @Farzah11

    I checked the matplotlib.org repository and did not find any existing PR adding a visible link to the stable PDF documentation. I would like to propose a clear link to the stable PDF (Matplotlib.pdf).Before proceeding, could you please confirm whether the intended change should be implemented in the matplotlib.org repository (homepage link) or within the main Matplotlib repository documentation? I want to ensure I open the PR in the correct place.

  8. melissawm commented on Feb 20, 2026

    @melissawm
    Member

    Hi @Farzah11, I'll try to summarize:

    So, depending on where you want to include the PDF docs, you should look for a suitable solution in one of these files.

    Cheers!

  9. Farzah11 commented on Feb 22, 2026

    @Farzah11

    Hi @melissawm , thanks for your guidance earlier :)
    I’d like to add a visible link to Matplotlib.pdf for easier access. Could you please confirm whether this should go on the homepage or in the stable docs sidebar? I want to make sure I open the PR in the correct repo.

  10. melissawm commented on Feb 23, 2026

    @melissawm
    Member

    Hi @Farzah11, I think this is part of the solution of the issue: deciding on the best place to put this.

    My personal opinion is that next to the cheatsheets works well, but you are welcome to provide your own solution.

    Cheers!

  11. story645 commented on Feb 23, 2026

    @story645
    Member

    I think that's three votes for under the cheatsheet pdf? I think give it a day to see if anyone is against, and if not go for it.

    I also think that while @SuperCowProducts didn't report a docs issue, #31173 (comment) would be an improvement to the docs.

  12. amishamehta99 commented on Mar 9, 2026

    @amishamehta99
    Contributor

    Hi! I’d like to work on adding a visible link to the PDF documentation near the cheatsheets section, as suggested in the discussion. Please let me know if that sounds good.
    @story645 @timhoffm @melissawm

  13. 37 remaining items

  14. amishamehta99 commented on Mar 24, 2026

    @amishamehta99
    Contributor

    Hi! I’ve been following the discussion and I understand that the preferred direction is to add a visible link to the PDF documentation near the cheatsheets section.

    Before starting any implementation, I just wanted to confirm:

    Should the PDF link be added as a secondary button alongside the existing cheatsheet buttons? And should it follow the same theme styling (size, spacing, colors)?

    I’d be happy to help once the placement and design direction are finalized.

    Acc to the way we have been working on this issue, the goal is to understand the ui. The maintainers are actively helping out in the filtering. Thanks.

  15. aishwaryabnateekar-ui commented on Mar 24, 2026

    @aishwaryabnateekar-ui

    Hi! I explored a few UI options and wanted to propose a simple approach.

    Proposed idea:
    Place a “Download PDF Documentation” link directly below the existing cheatsheets section in the sidebar.

    Why this approach:

    • Keeps the layout clean and avoids overcrowding the sidebar
    • Maintains visual separation between cheatsheets and documentation
    • Easy for users to discover without disrupting existing UI structure

    Implementation idea:

    • Add a small text link or subtle button below the cheatsheet images
    • Keep spacing consistent with existing elements
    • Ensure it remains clearly visible and clickable

    If this direction looks good, I can work on implementing it.

    Happy to refine based on feedback!

  16. story645 commented on Mar 24, 2026

    @story645
    Member

    The decision left here is if the different color button idea in #31173 (comment) solves the issue.

    I think it's good enough, but would like sign off from at least one other maintainer.

  17. amishamehta99 commented on Mar 24, 2026

    @amishamehta99
    Contributor

    Would love to get feedback from another maintainer when possible.

    The decision left here is if the different color button idea in #31173 (comment) solves the issue.

    I think it's good enough, but would like sign off from at least one other maintainer.

  18. jklymak commented on Mar 24, 2026

    @jklymak
    Member

    I feel like we are using this sidebar as a "put junk we don't know what to do with here", but the proposal seems fine if this is where you are going to put it. I'd just say "PDF docs [18 Mb]" or "PDF documentation" rather than a long sentence...

  19. story645 commented on Mar 25, 2026

    @story645
    Member

    feel like we are using this sidebar as a "put junk we don't know what to do with here"

    I suggested it b/c I thought the link used to live there b/c there used to be a box w/ the versions there. If we want something less prominant, then maybe the footer? Which I think yes, the biggest issue is that it's not really clear where this would be discoverable if we don't make it a button on the homepage.

  20. jklymak commented on Mar 25, 2026

    @jklymak
    Member

    Why did we remove the version box?

    I think we could move ahead w whatever has been decided for now and the someone can go and fix it later

  21. story645 commented on Mar 25, 2026

    @story645
    Member

    Why did we remove the version box?

    Cause we have that info in the dropdown, though for a bit we had both.

  22. amishamehta99 commented on Mar 25, 2026

    @amishamehta99
    Contributor

    Why did we remove the version box?

    Cause we have that info in the dropdown, though for a bit we had both.

    Thanks @story645 @jklymak . Should I proceed with adding a minimal 'PDF docs [18 mb]' link in the sidebar for now? Happy to adjust placement later if needed.

  23. amishamehta99 commented on Mar 25, 2026

    @amishamehta99
    Contributor

    Why did we remove the version box?

    Cause we have that info in the dropdown, though for a bit we had both.

    Thanks @story645 @jklymak . Should I proceed with adding a minimal 'PDF docs [18 MB]' link in the sidebar for now? Happy to adjust placement later if needed.

  24. amishamehta99 commented on Mar 25, 2026

    @amishamehta99
    Contributor

    Maintainers, I’ve been contributing to Matplotlib recently (a few of my PRs have been merged), and while working on documentation-related issues, I noticed some inconsistencies across documentation versions.
    For example, minor version differences (like 3.10.0 vs 3.10.8) are treated quite differently with warning banners, and there are also variations in installation options and UI layout across versions. This can be confusing, especially for beginners.
    I’m thinking of focusing my GSoC proposal on improving versioning consistency and reducing this kind of documentation friction.
    Would love to get your thoughts on whether this direction seems useful, or if there are specific areas I should focus on?

  25. story645 commented on Mar 25, 2026

    @story645
    Member

    Would love to get your thoughts on whether this direction seems useful, or if there are specific areas I should focus on?

    Can you make this a new issue or discourse topic so it doesn't derail this one. Generally documentation is out of scope for GSoC unless it's heavily infrastructure focused. Also please provide screenshots/links explaining what the issues are, b/c my instinctual response is to wonder if you are confused about how document versioning works.

  26. aishwaryabnateekar-ui commented on Mar 29, 2026

    @aishwaryabnateekar-ui

    Hi! Based on the discussion so far, it seems we are leaning toward a minimal solution like "PDF docs [18 MB]".

    To help move toward consensus, I wanted to clarify:

    1. Should we finalize placement as:

      • Sidebar (near cheatsheets), or
      • Footer (less prominent but cleaner)?
    2. Should we proceed with a simple text link first, and iterate later if needed?

    Happy to implement once direction is finalized.

  27. amishamehta99 commented on Mar 31, 2026

    @amishamehta99
    Contributor

    Hi Maintainers. Update on this one? Should we proceed ahead with the changes or stop it here temporarily for sometime?

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions