docs: table and add stars

[henryiii]

Adds a table, with a new stars column, and sorts by stars.

• docs: repo table with stars
• docs: sort by stars

[henryiii]

@joerick If you like this, then I'll add scikit-learn, scikit-image (seems to have converted 7 days ago), google/neuroglancer, h5py, pyzmq, python-rapidjson, jq.py, the three pybind11 examples, and the Scikit-HEP repos.

[joerick]

Would be great to add those extra repos you mentioned! scikit-learn is a big one, good job team!

On the formatting, unfortunately HTML table formatting is crushing the stars column...

I wonder if a more compact badge would solve that? I played around with shields.io and came up with this-

https://img.shields.io/github/stars/joerick/cibuildwheel?color=white&label=%20&logo=reverbnation&logoColor=%23333&style=flat-square

Which looks like:

I might be going too far, but another thought would be to add a logo for the CI service they're using, like

(for reference, available icons are listed here)

[henryiii]

I could also just put the stars with the name, instead of in a column, or I could do GH Stars for the title, which makes it a bit wider. I also considered putting a "Last updated" badge, which would help us clean up ones that are dead. The downside with adding CI logos is that we'd have to manually maintain that. I do like the idea of reducing the notes to 1 line, so maybe CI + OSs would make that really just a quick note.

[henryiii]

I also tried playing with GHA, and had this as a replacement for the title, like or .

[henryiii]

Name	Stars	CI	OS	Notes
Matplotlib				The venerable Matplotlib, a Python library with C++ portions
twisted-iocpsupport				A submodule of Twisted that hooks into native C APIs using Cython.
websockets
aiortc
coverage.py				The coverage tool for Python
creme
PyAV
aioquic
AutoPy
pikepdf
Parselmouth				A Python interface to the Praat software package, using pybind11, C++17 and CMake, with the core Praat static library built only once and shared between wheels.
KDEpy
bx-python				A library that includes Cython extensions.
pybase64
TgCrypto
etebase-py				Python bindings to a Rust library using setuptools-rust, and sccache for improved speed.
gmic-py
fathon
pyinstrument_cext				A simple C extension, without external dependencies
python-admesh
xmlstarlet				Python 3.6+ CFFI bindings with true MSVC build.
apriltags2-ethz

<!-- Matplotlib: 12714, last pushed 0 days ago -->
<!-- twisted-iocpsupport: 4099, last pushed 5 days ago -->
<!-- websockets: 3045, last pushed 3 days ago -->
<!-- aiortc: 2046, last pushed 2 days ago -->
<!-- coverage.py: 1420, last pushed 0 days ago -->
<!-- creme: 1153, last pushed 2 days ago -->
<!-- PyAV: 1105, last pushed 23 days ago -->
<!-- aioquic: 538, last pushed 30 days ago -->
<!-- AutoPy: 500, last pushed 86 days ago -->
<!-- pikepdf: 468, last pushed 3 days ago -->
<!-- Parselmouth: 423, last pushed 7 days ago -->
<!-- KDEpy: 223, last pushed 4 days ago -->
<!-- bx-python: 95, last pushed 67 days ago -->
<!-- pybase64: 51, last pushed 0 days ago -->
<!-- TgCrypto: 48, last pushed 17 days ago -->
<!-- etebase-py: 39, last pushed 3 days ago -->
<!-- gmic-py: 15, last pushed 0 days ago -->
<!-- fathon: 15, last pushed 41 days ago -->
<!-- pyinstrument_cext: 8, last pushed 9 days ago -->
<!-- python-admesh: 8, last pushed 893 days ago -->
<!-- xmlstarlet: 7, last pushed 10 days ago -->
<!-- apriltags2-ethz: 1, last pushed 567 days ago -->

[henryiii]

I'd also propose we remove python-admesh and apriltags2-ethz, as they haven't been updated in over a year. We need to fill out the various CI platforms and OS's eventually, I've just converted was was in notes to icons.

[YannickJadoul]

Cool! Btw, I'm not sure it's worth depending on that, but I recently used PyGithub (to download artifacts from GitHub builds to ReadTheDocs), and I really liked it :-) So maybe you can loose a few manual API queries?

[YannickJadoul]

(Somehow, the stars still get scaled, though?)

[henryiii]

Everything is scaled by the width of the column. Try editing the above post to add lots of  's to the titles, and see what happens. I've tweaked it a little, it's marginally better now.

The main point of stars was to sort this - now that we read the stars and sort it via the script, we could drop the stars.

I think I'd only use PyGithub if the API limiting feature became an issue, since it allows you to log in more easily.

[henryiii]

New version. It can now embed the output in the readme for you, and it also uses PyGithub with optional authentication since I was running it too often. Adds the GitHub description (with a little book icon) if no description was given.

PS: I missed a couple when checking CI & OS, will add next update - also didn't update ones that were already there, like twisted)

Name	Stars	CI	OS	Notes
scikit-learn				📕 scikit-learn: machine learning in Python
Matplotlib				The venerable Matplotlib, a Python library with C++ portions
twisted-iocpsupport				A submodule of Twisted that hooks into native C APIs using Cython.
scikit-image				📕 Image processing in Python
websockets				📕 Library for building WebSocket servers and clients in Python
pyzmq				📕 PyZMQ: Python bindings for zeromq
aiortc				WebRTC and ORTC implementation for Python using asyncio.
h5py				📕 HDF5 for Python -- The h5py package is a Pythonic interface to the HDF5 binary data format.
coverage.py				The coverage tool for Python
creme				📕 🌊 Online machine learning in Python
PyAV				Pythonic bindings for FFmpeg's libraries.
google/neuroglancer				📕 WebGL-based viewer for volumetric data
aioquic				📕 QUIC and HTTP/3 implementation in Python
AutoPy				Includes a Windows Travis build.
pikepdf				📕 A Python library for reading and writing PDF, powered by qpdf
Parselmouth				A Python interface to the Praat software package, using pybind11, C++17 and CMake, with the core Praat static library built only once and shared between wheels.
python-rapidjson				📕 Python wrapper around rapidjson
KDEpy				📕 Kernel Density Estimation in Python
pybind11:python_example				📕 Example pybind11 module built with a Python-based build system
pybind11:cmake_example				📕 Example pybind11 module built with a CMake-based build system
iminuit				📕 Jupyter-friendly Python interface for C++ MINUIT2
jq.py				📕 Python bindings for jq
bx-python				A library that includes Cython extensions.
boost-histogram				Supports full range of wheels, including PyPy and alternate archs.
pybase64				📕 Fast Base64 encoding/decoding in Python
TgCrypto				Includes a Windows Travis build.
etebase-py				Python bindings to a Rust library using setuptools-rust, and sccache for improved speed.
pyjet				📕 The interface between FastJet and NumPy
numpythia				📕 The interface between PYTHIA and NumPy
gmic-py				📕 Python binding for the G'MIC Image Processing Framework
fathon				📕 python package for DFA (Detrended Fluctuation Analysis) and related algorithms
pyinstrument_cext				A simple C extension, without external dependencies
xmlstarlet				Python 3.6+ CFFI bindings with true MSVC build.
pybind11:scikit_build_example				📕 An example combining scikit-build and pybind11

<!-- scikit-learn: 43276, last pushed 0 days ago -->
<!-- Matplotlib: 12714, last pushed 0 days ago -->
<!-- twisted-iocpsupport: 4100, last pushed 5 days ago -->
<!-- scikit-image: 4073, last pushed 0 days ago -->
<!-- websockets: 3047, last pushed 4 days ago -->
<!-- pyzmq: 2650, last pushed 1 days ago -->
<!-- aiortc: 2046, last pushed 2 days ago -->
<!-- h5py: 1450, last pushed 1 days ago -->
<!-- coverage.py: 1421, last pushed 0 days ago -->
<!-- creme: 1153, last pushed 3 days ago -->
<!-- PyAV: 1105, last pushed 23 days ago -->
<!-- google/neuroglancer: 545, last pushed 0 days ago -->
<!-- aioquic: 538, last pushed 30 days ago -->
<!-- AutoPy: 500, last pushed 86 days ago -->
<!-- pikepdf: 468, last pushed 3 days ago -->
<!-- Parselmouth: 423, last pushed 7 days ago -->
<!-- python-rapidjson: 405, last pushed 5 days ago -->
<!-- KDEpy: 224, last pushed 5 days ago -->
<!-- pybind11:python_example: 217, last pushed 25 days ago -->
<!-- pybind11:cmake_example: 214, last pushed 8 days ago -->
<!-- iminuit: 163, last pushed 0 days ago -->
<!-- jq.py: 137, last pushed 54 days ago -->
<!-- bx-python: 95, last pushed 68 days ago -->
<!-- boost-histogram: 60, last pushed 0 days ago -->
<!-- pybase64: 51, last pushed 0 days ago -->
<!-- TgCrypto: 48, last pushed 17 days ago -->
<!-- etebase-py: 39, last pushed 3 days ago -->
<!-- pyjet: 27, last pushed 10 days ago -->
<!-- numpythia: 23, last pushed 8 days ago -->
<!-- gmic-py: 15, last pushed 0 days ago -->
<!-- fathon: 15, last pushed 41 days ago -->
<!-- pyinstrument_cext: 8, last pushed 10 days ago -->
<!-- xmlstarlet: 7, last pushed 10 days ago -->
<!-- pybind11:scikit_build_example: 1, last pushed 23 days ago -->

[henryiii]

I haven't seen how this renders on RtD, maybe @joerick you could check that? By the way, why is the changelog stripped from read the docs? I missed it for a while because I didn't realize the RtD page and GitHub page were not the same (and the changelog is the most important part of the docs to me ;) )

[joerick]

This is looking quite good! And I love how it's automated. ✨ It's quite visually busy, maybe we don't need the stars column after all? And the book emoji is too loud. I'm happy to have a go at writing/copying something into the notes section for each, as perhaps we don't want people being lazy and sending us PRs without the notes filled out.

I haven't seen how this renders on RtD, maybe @joerick you could check that?

RtD renders each PR as a 'check', you can see how it comes out - https://cibuildwheel--474.org.readthedocs.build/en/474/ - but the short answer is that it isn't included! Not all the README is included in that home page, just the introduction, which sets out what cibuildwheel does, before the docs head into the setup guide.

By the way, why is the changelog stripped from read the docs? I missed it for a while because I didn't realize the RtD page and GitHub page were not the same (and the changelog is the most important part of the docs to me ;) )

When this was set up the goal was mostly to just get an intro to the project into that first page of the docs, not to recreate the entire readme. But if you're saying that you miss that content in the docs site (and I do find it awkward to find the link to Github from the docs site), maybe we should add another page with changelog included. I'd only suggest that it was a separate page so that the first 'Home' page isn't too long.

As for what we do about this table, I'm guessing you'd be in favour of including it? I think that makes sense too (1). It could be another page in the docs - "Working examples"/"Inside real projects"/"As seen in…"/"In the wild"

(1): So far, I've always felt that the Github project is the 'home' of the project, and the docs is an external resource. But I think your angle seems to be that docs is the 'home'. And it does seem that most Python projects at some point make that switch, although personally I've always preferred going to Github to get README, issues, dip into code etc. What do you think?

[YannickJadoul]

So far, I've always felt that the Github project is the 'home' of the project, and the docs is an external resource.

I also tend to take that stance, I think, but the most important point is that things are linked and you can easily go from one to the other.
That being said, the changelog does seem to be often hidden in the docs (and actually not in the README), though? I don't mind it being in the README, so far, but I can see why @henryiii expects to find that in the docs.

[henryiii]

I think the docs site should be reasonably complete - a list of projects would be very useful on the docs site, and the list of changes would be nice too, though not as critical. The docs site has everything a user needs in one place - to me, this should always include the changelog. Ideally, there would be a changes or what's new page, and an example projects page. There's nothing wrong with having it in the readme on GitHub - though having the changelog in the readme is not that common, and scrolling down on the already long page is easy to miss, especially to someone who already looked at the RtD page and thinks they are the same (that happened to me). I generally look for a CHANGELOG.md file or similar in the repo, or a contents item in the docs, or in the GitHub releases (which it just recently started being mirrored in). Bottom of the readme is not at all where I'd expect it to be. A developer should be expected to be able to find things where they normally are in other projects. Not saying it has to move, but I would at least like it available somewhere in the docs. :)

I also value linking back and forth - I always use the GitHub project URL to go to the docs (which is actually available in the API, which I didn't realize before! Off topic), and I use the link at the top right of the docs to go to the repo (edit this page, fork me, etc). It drops me in edit mode for some repos (like this one), but it's universal and a fast way to get to the GitHub without having to dig in RtD's menu or look for a link that is different in each project. And getting to the home page is one click away even if it is in edit mode.

TLDR: Having two pages that start with the same content but then the one that is already longer (due to file list) has more information at the bottom is not very friendly. Especially when that content is only available there and not on the other site or in a commonly named file.

[henryiii]

creme -> river, and GMIC doesn't seem to use cibuildwheel anymore (moved to back up folder - custom speggetti mess of scripts (it might be that cibuildwheel was only being used for Windows, and the author gave up on Windows). This should be updated except for notes.

Stars was there to make it easier to sort - but now we sort by stars anyway. :)

Name	CI	OS	Notes
scikit-learn			📕 scikit-learn: machine learning in Python
Matplotlib			The venerable Matplotlib, a Python library with C++ portions
twisted-iocpsupport			A submodule of Twisted that hooks into native C APIs using Cython.
scikit-image			📕 Image processing in Python
websockets			📕 Library for building WebSocket servers and clients in Python
pyzmq			📕 PyZMQ: Python bindings for zeromq
aiortc			WebRTC and ORTC implementation for Python using asyncio.
h5py			📕 HDF5 for Python -- The h5py package is a Pythonic interface to the HDF5 binary data format.
coverage.py			The coverage tool for Python
River			📕 🌊 Online machine learning in Python
PyAV			Pythonic bindings for FFmpeg's libraries.
google/neuroglancer			📕 WebGL-based viewer for volumetric data
aioquic			📕 QUIC and HTTP/3 implementation in Python
AutoPy			Includes a Windows Travis build.
pikepdf			📕 A Python library for reading and writing PDF, powered by qpdf
Parselmouth			A Python interface to the Praat software package, using pybind11, C++17 and CMake, with the core Praat static library built only once and shared between wheels.
python-rapidjson			📕 Python wrapper around rapidjson
KDEpy			📕 Kernel Density Estimation in Python
pybind11:python_example			📕 Example pybind11 module built with a Python-based build system
pybind11:cmake_example			📕 Example pybind11 module built with a CMake-based build system
iminuit			📕 Jupyter-friendly Python interface for C++ MINUIT2
jq.py			📕 Python bindings for jq
bx-python			A library that includes Cython extensions.
boost-histogram			Supports full range of wheels, including PyPy and alternate archs.
pybase64			📕 Fast Base64 encoding/decoding in Python
TgCrypto			Includes a Windows Travis build.
etebase-py			Python bindings to a Rust library using setuptools-rust, and sccache for improved speed.
pyjet			📕 The interface between FastJet and NumPy
numpythia			📕 The interface between PYTHIA and NumPy
fathon			📕 python package for DFA (Detrended Fluctuation Analysis) and related algorithms
pyinstrument_cext			A simple C extension, without external dependencies
xmlstarlet			Python 3.6+ CFFI bindings with true MSVC build.
pybind11:scikit_build_example			📕 An example combining scikit-build and pybind11

<!-- scikit-learn: 43307, last pushed 0 days ago -->
<!-- Matplotlib: 12725, last pushed 0 days ago -->
<!-- twisted-iocpsupport: 4100, last pushed 0 days ago -->
<!-- scikit-image: 4078, last pushed 0 days ago -->
<!-- websockets: 3058, last pushed 6 days ago -->
<!-- pyzmq: 2651, last pushed 4 days ago -->
<!-- aiortc: 2052, last pushed 5 days ago -->
<!-- h5py: 1450, last pushed 4 days ago -->
<!-- coverage.py: 1424, last pushed 0 days ago -->
<!-- River: 1162, last pushed 0 days ago -->
<!-- PyAV: 1106, last pushed 26 days ago -->
<!-- google/neuroglancer: 545, last pushed 0 days ago -->
<!-- aioquic: 538, last pushed 33 days ago -->
<!-- AutoPy: 501, last pushed 89 days ago -->
<!-- pikepdf: 471, last pushed 6 days ago -->
<!-- Parselmouth: 424, last pushed 10 days ago -->
<!-- python-rapidjson: 406, last pushed 1 days ago -->
<!-- KDEpy: 224, last pushed 7 days ago -->
<!-- pybind11:python_example: 218, last pushed 27 days ago -->
<!-- pybind11:cmake_example: 216, last pushed 11 days ago -->
<!-- iminuit: 164, last pushed 0 days ago -->
<!-- jq.py: 137, last pushed 57 days ago -->
<!-- bx-python: 95, last pushed 70 days ago -->
<!-- boost-histogram: 60, last pushed 3 days ago -->
<!-- pybase64: 51, last pushed 0 days ago -->
<!-- TgCrypto: 48, last pushed 19 days ago -->
<!-- etebase-py: 39, last pushed 6 days ago -->
<!-- pyjet: 27, last pushed 12 days ago -->
<!-- numpythia: 23, last pushed 11 days ago -->
<!-- fathon: 16, last pushed 44 days ago -->
<!-- pyinstrument_cext: 9, last pushed 12 days ago -->
<!-- xmlstarlet: 7, last pushed 0 days ago -->
<!-- pybind11:scikit_build_example: 1, last pushed 25 days ago -->

[henryiii]

PS: the logos are a bit hard to see in GitHub: dark mode. https://github.blog/2020-12-08-new-from-universe-2020-dark-mode-github-sponsors-for-companies-and-more/

Opened issue here: https://github.community/t/uncolored-svg-should-be-white-in-dark-mode/147914

[YannickJadoul]

Just noticed: if I wanted to be nitpicky, I'd say that bin/projects.yml is a bit weird, because it's not something to run. But I also don't have a better location (docs also seems weird, no?). Mentioning this in case it's there by accident and anyone would really care about it; otherwise, don't move it on my behalf!

[henryiii]

I didn't want to put in in the main directory, and had no idea where else to put it. :) Happy to move it if someone has a better spot.

[YannickJadoul]

Happy to move it if someone has a better spot.

Since we have no random collection of files etc or misc, only place I can think of is docs, which is not fully correct either. But I don't really mind. As you (or @joerick?) prefer :-)

[joerick]

Hi @henryiii, I hope you don't mind I did a little work on this. I've added a few notes on the popular projects, but to be completely honest I got a little bored so didn't do it for all the projects 🙃. I see there's still an issue around dark mode for the icons, I'm wondering if something like #404040 would be visible on both, and also I'd like those icons to have explicit widths as currently they're sized according to the whims of the HTML table size algorithm, so I'm thinking we could vendor them into the project and tweak them how we like.

[henryiii]

so I'm thinking we could vendor them into the project and tweak them how we like

Ah, good idea. I didn't want to inject the html into the table, so didn't have a solution for the sizing - vendored icons likely would work well.

[joerick]

See https://cibuildwheel--474.org.readthedocs.build/en/474/working-examples/ for how it now looks in the docs. I also added the changelog to the docs too. I'm pretty happy with where this is now, what do you think @henryiii ?

[henryiii]

LGTM!

[henryiii]

@joerick Don't think this is working as planned: https://cibuildwheel.readthedocs.io/en/latest/working-examples/

[joerick]

Oh that's weird! It was working in the PR. Oh, I guess the PR was in my vendored include plug-in and master is on the new broken-out one. Thanks for spotting this! I'll get a fix out tomorrow