search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
70 stars 43 forks source link

use literalinclude in code-style-linting-format #259

Closed ucodery closed 1 month ago

ucodery commented 1 month ago

Tagging #250

lwasser commented 1 month ago

ok i see now @ucodery IGNORE all of my comments. this looks great. I think i have one request but i'm not sure how to implement this. What you are adding is really cool. essentially someone can test out how linters work.

i feel like we want instructions around doing this. I also feel like we could ask some of the myst folks about better ways to make it more clearly interactive. because what you have done here is really really great.

so take aways

  1. let's merge this! ignore my review. i now feel silly that i left those comments.
  2. how can we call more attention to the fact that you're adding more interactive activities to the page (which is awesome)?? -- in a separate issue we could discuss.
ucodery commented 1 month ago

A few clarifications:

These example projects are not yet full projects (I think any would build, but e.g. pure-hatch contains no python code right now). #248 is open for getting us to multiple really usable example projects.

These literalinclude PRs I've been making are just the first steps and are only about moving toml and python code that already existed in markdown into their own files; like taking a jupyter monolith and extracting some pure python modules.

I'm not trying to make any drastic changes, and I consider it a success when I make 0 changes to the rendered site after literalinclude. So although I agree that the python world has moved fast and a lot has changed in just the last year, I think those changes should be considered in separate issues.

As for how readers will interact with these examples, right now they are still just code blocks in the guide. Nothing here makes examples runnable. In order to test any of it out a reader would likely have to clone the repo and cd to the example and use CLI/ IDE to play around; they might even have to copy out the example code into a new project, to test git hooks for example.