Potential minor improvements on Creating an open source Python project from scratch

[TAdeJong]

You seem very cool with receiving feedback on this very cool blog, so I will drop in some observations/suggestions :-) Please feel free to ignore any that don't make sense!

• codecov v1 of codecov/codecov-action will be deprecated early next year. v2 was a straight forward drop-in for me, although I had to specify xml output for pytest in setup.cfg:

[tool:pytest]
addopts = --cov=pyGPA --cov-report=term --cov-report=xml

• I believe you were already aware that your suggestion to use numpydoc docstrings is well-received, but that info on enabling sphinx.ext.napoleon or something similar to render them correctly in documentation is missing.
• Something that would have helped me enormously in the readthedocs piece: make sure to update your packages before rendering locally, or to pin dependency versions to prevent unpleasant surprises.
• setup.py packaging.python.org seems to push for a pyproject.toml in combination with a setup.cfg. My understanding of PEP 517 and 518 doesn't go far enough to understand the implications of all this, but the contrast between your post and packaging.python.org stood out. It might be something to at least mention? (Although I understand you don't want to sum all possible alternatives everywhere...)

[jacobtomlinson]

Thanks for the feedback this is really helpful!

codecov

Awesome that's a quick fix.

napoleon

Yeah I need to go back and add that.

readthedocs ... update your packages ... or to pin dependency versions

Could you expand on this? What problems were you having?

pyproject.toml

I've heard a little about pyproject.toml but I've never used it in a project. I'm aware that the current trend is to move static metadata out of setup.py and into setup.cfg. I should get more familiar with this and then go back and update things.

[TAdeJong]

readthedocs ... update your packages ... or to pin dependency versions

Could you expand on this? What problems were you having?

Looking back probably more nbsphinx related than readthedocs directly, but I had a weird internal error for the latex rendering on sphinx=4.1.2, which was newer than what I had locally, and ended up pinning on 3.5.4, I missed 2 non-obvious dependencies (because of course I already locally had added matplotlib to my env) and then a newer matplotlib version on readthedocs decided to throw an error my older local version didn't throw.

Nothing crazily unexpected, and all fixable, but the warning to carefully check env versions and requirements beforehand would have saved me quite some googling headache and awkward extra commits :-)

[jsignell]

Just came across this series again. It's great Jacob! Having just set up a new project for the first time in a while it seems like the current trend it to just have a pyproject.toml and not a setup.cfg or a setup.py

[jacobtomlinson]

Just came across this series again.

Yay! Yeah I was also setting up a new project yesterday and did it all with pyproject.toml. Maybe this series is due an update.

I would probably also use ruff over many of the linting tools I used to use.