search

christopher-wild / FAIR4RS-Packaging

https://christopher-wild.github.io/FAIR4RS-Packaging/
Other
1 stars 0 forks source link

Feedback: Section 2. History! #17

Open christopher-wild opened 5 months ago

christopher-wild commented 5 months ago

Render first solution better

f-allian commented 5 months ago

@christopher-wild Hint syntax

:::::::::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::: challenge

Challenge 1

:::::::::::::::::::::::: hint

Hint

Hint here

:::::::::::::::::::::::::::::::::

:::::::::::::::::::::::: solution

Solution

Solution here

::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::::::::::

christopher-wild commented 5 months ago

Fibonacci throughout the episodes.

christopher-wild commented 5 months ago

Render markdown link better

christopher-wild commented 5 months ago

missing keypoints

christopher-wild commented 5 months ago

Make it clearer which is the best and latest standard

christopher-wild commented 5 months ago

Compress this episode, its a good to know not need to know

christopher-wild commented 5 months ago

Add challenge: Research solutions and note which package standards are recommended

Joe-Heffer-Shef commented 5 months ago

add link to https://docs.python.org/3/library/venv.html

ns-rse commented 5 months ago

Sorry to miss the review the other day I had school pickup that was bang in the middle.

Reading through this section I'm curious what the motivation is for mentioning older and dated package configuration options such as requirements.txt / setup.py / setup.cfg is?

PEP621 proposed pyproject.toml as the standard and has been accepted and both the Python Packaging User Guides and the Scientific Python Packaging Tutorial both only mention/describe/show how to use pyproject.toml.

It seems a bit redundant to be referencing these when they are dated and we should be teaching people current practices. I guess it would be ok to mention them briefly afterwards that there are older ways that were used should they encounter other packages that haven't updated but the focus should be on teaching them one, current, way of doing things.

ns-rse commented 5 months ago

On a more technical aspect it might be worth incorporating into the pyproject.toml description the use of setuptools_scm which makes versioning of releases as simple as applying a tag to a commit.

To do so you need to have the following in pyproject.toml

[build-system]
requires = [
  "setuptools>=45",
  "setuptools_scm[toml]>=6.2",
  ]
build-backend = "setuptools.build_meta"
...
[tool.setuptools_scm]
write_to = "_version.py"
christopher-wild commented 5 months ago

Sorry to miss the review the other day I had school pickup that was bang in the middle.

Reading through this section I'm curious what the motivation is for mentioning older and dated package configuration options such as requirements.txt / setup.py / setup.cfg is?

PEP621 proposed pyproject.toml as the standard and has been accepted and both the Python Packaging User Guides and the Scientific Python Packaging Tutorial both only mention/describe/show how to use pyproject.toml.

It seems a bit redundant to be referencing these when they are dated and we should be teaching people current practices. I guess it would be ok to mention them briefly afterwards that there are older ways that were used should they encounter other packages that haven't updated but the focus should be on teaching them one, current, way of doing things.

No worries for missing it, thank you for taking the time to go through it! We're playing to have a more formal go through them like your session in the next few weeks.

The motiviation for at least setup.py is that when beginners are looking up 'how to do x in python packaging' a lot of the information out there still pertains to setup.py files. I think it's nice to at least understand what that file was and why we moved away from it so when they read older threads and guides they aren't confused.

One of the take aways from our session though is to cut back on how long this is! They probably don't need to know as much as is in here. I'll probably remove setup.cfg all together as well.

ns-rse commented 4 months ago

Volume is something I also made a mistake on.

I had similar feedback on redundant explanations for my material (i.e. why teach git commit --ammend and git commit --fixup when they are really just short-cuts for git rebase -i) and do appreciate and understand the gentle introduction approach.

After reading through more of the course material I can see the pyproject.toml has been adopted :+1:

ns-rse commented 3 days ago

Was browsing around the training material and noticed that in Packaging history...

List doesn't render correctly in solution

Line 66 the list doesn't render correctly. I think this is because there is no space between the preceding paragraph and the first numbered item in the list.

First link under pyproject.toml doesn't render

The markup for the link on Line 135 is back to front it should be square brackets around the text and parentheses around the link...

Current

(PEP517)[https://peps.python.org/pep-0517/]

Should be

[PEP517](https://peps.python.org/pep-0517/)

Same problem on Line 153. Haven't checked other episodes.

Aside A useful browser plugin I use for copying links in different formats is Copy URL to Clipboard, it supports multiple formats and those you won't use can be disabled, and you can bind a particular format to a key sequence, e.g. I bind copying to Markdown to Alt + M and Org-mode to Alt +O making it really quick and easy to copy and paste URLs

Linting

These errors (and perhaps others) might have been caught by the markdownlint-cli2 linter which can be setup to work with .Rmd files and enabled as a pre-commit hook (and you can also set it up to run in GitHub courtesy of pre-commit.ci. It might be worth running the code base past the linter to see what it throws up.