matplotlib / mpl-third-party Goto Github PK

So got a request to add https://www.python-graph-gallery.com/ to the mpl docs & wondering now if this repo can be used to spawn a second page to replace https://matplotlib.org/stable/resources/index.html#books-chapters-and-articles. or maybe a second version of this repo for that kind of thing, since presumably we want a slightly higher barrier to entry but there are lots of folks building really good learning resources and it might be useful to have a place they can self register.

It's basically doubled here:

Saw the suggestion in this Tweet to let you know about 3rd party packages

For quite some time, PySimpleGUI has integrated with matplotlib. There are currently 13 "Demo Programs" that help users get a jump start on adding a GUI to their matplotlib programs.

Here's one that shows a number of sample graphs from the matplotlib gallery page.

Others spotlight how little code is needed to make a plot.

Not sure where to put information like this on this GitHub site. Maybe you can help?

Problem

I think one of the features of the old third party page is the ability to see images that represent what a library can do. I think this makes scanning much easier if you are just trying to discover what is out there. For instance this:

is pretty tricky for me to get a sense of what each these really do on a quick scan through if I just wanted to see what is out there.

Proposed Solution

I understand that there shouldn't be images on the main third party page, but what if when you clicked on the headings it took you to a subpage that included images/gifs?

Or perhaps a button that could be clicked to expand and show an image/gif

Currently they don't work if on https://matplotlib.org/mpl-third-party/, which is too bad. Also I noticed one name is different compared to the mpl 3.5 docs ("User guide" vs "Usage guide"). And Sphinx major version in the published build is 2 behind that used in the mpl docs according to the footer.

Provide popularity-related information for the projects, e.g.

• github stars
• PyPI installs

Format and content t.b.d.

This should help users to see whether the project is something substantial or rather a small side-project.

As part of implementing #71, it might be good to pull the external-resources link in https://matplotlib.org/devdocs/users/index.html and instead have the third-party link in the header link out to a landing page that itself links out to the resources and libraries page.

• con one more layer of indirection 3PP->libraries->library page, 3PP->resources->resources page
• pros:
  • resources is currently buried in users->guide->resources so linking cost is net zero
  • puts building education resources on equal footing w/ building downstream libraries
  • process to contribute to both will be the same (+/- keywords) & lets us lead w/ make your own (like in the readme, which more or less probably could serve as the landing page)

They both use matplotlib and have their own wrappers.

Are there any limits on what keywords can/should be?

Problem

Currently there is no way to link to a specific section.

Proposed Solution

Modify the HTML so that the section headers can be refered to with something like ...url...#Animations and add a clickable permalink style thing like Github renders for markdown:

The css is hard coded in template.html currently. Probably should be cleaned up and made proper css...

Since #112 it looks like the GitHub pages builds have been failing with a html_permalinks_icon key error (which means the last 4 tools to be merged (microfilm, tueplots, grplot and distinctipy) are not appearing on the docs page.

E.g. see this latest build: https://github.com/matplotlib/mpl-third-party/runs/7224799482?check_suite_focus=true

Exception occurred:
  File "/usr/local/lib/python3.8/site-packages/pydata_sphinx_theme/__init__.py", line 45, in update_config
    icon_default = app.config.values["html_permalinks_icon"]
KeyError: 'html_permalinks_icon'
The full traceback has been saved in /tmp/sphinx-err-kzajtp7a.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:21: html] Error 2
Traceback (most recent call last):
  File "/entrypoint.py", line 22, in <module>
    action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
  File "/sphinx_action/action.py", line 167, in build_all_docs
    raise RuntimeError("Build failed")
RuntimeError: Build failed

Um what are the merge rules on this repo? If same as matplotlib, do new yml files count as docs?

Currently we cannot parse arbitrary url for repo... See #91

Add https://github.com/znstrider/highlight_text

Make sure descriptions all start with capital and end with period. These are all in packages/*.yml.

This is a very useful repo, thanks! Would it make sense to have another category "User APIs", which would include plotnine, pandas, xarray, and then holoviews and hvplot once I add those? Right now plotnine is under "Domain specific libraries" and xarray and pandas are under "Plot types", but I don't think plotnine is specific to any particular domain, and xarray and pandas are important for their .plot() APIs, not because they are special plot types. I think a category like "User APIs" would speak more to why a user might want to select any of those libraries, and I'm happy to make a PR to that effect if others agree.

Would be useful to have a script ./valid package.yml folks could run locally on the yml files they're contributing rather than having to wait for the CI. Or to set this up as a standalone github action when new .yml files in package are contributed.

Either way, would require refactoring the parsing code in build.py into a function that could either be called in the loop in build.py or in a standalone script.

Documentation Link

https://matplotlib.org/mpl-third-party/

Problem

Spelling mistake: On the above webpage, "approximatly" next to "mpl-qtthread" should be "approximately". If someone could point me to how I could fix this in the source, I would be grateful.

Suggested improvement

No response

Currently, we have a packages folder with one one file per package.

I propose to put everything together into a single YAML file, that contains a list of all the package infos.

It's easier to add new entries if you can see how the others look like. Also it's checking consistency (e.g. section names) is a bit simpler in a single file.

The relatively small fixed column width for the badges makes them awkwardly sized (the text size is different if the version is long). I realize that the full column width is smaller than at https://pyviz.org/tools.html which constrains things, but perhaps you could drop the "Name/Description/Github/..." headers and go for a 2-line-per-project layout?

Name <tab> Description (more likely to fit in a single line now as well)
    (github badge) (pypi badge) (conda badge)

possibly keeping a blank if there's no pypi badge so that conda badges stay aligned.

CI no longer triggers on PRs. Seems to work fine for commits...

Make it clearer what the section section of the yaml is and point people to the sections list - possibly autogenerated off a dictionary with discription. Also means pulling the sections dict out of build.py

See https://pypi.python.org/pypi/ModestImage/0.1 and https://github.com/ChrisBeaumont/mpl-modest-image.

While testing #64, I tried to run build_cache.py, but it failed. It started looking for a non-existent cache directory, but even after fixing that, it was looking for a non-existent tools.yml, and I don't know where that went.