Add M269 quick start guide

dsa-ou / algoesup

Algorithmic essays support: examples, templates, guides, library

https://dsa-ou.github.io/algoesup/

BSD 3-Clause "New" or "Revised" License

2 stars 0 forks source link

Add M269 quick start guide #11

Closed mwermelinger closed 8 months ago

mwermelinger commented 9 months ago

[x] Write a simpler guide for M269 students: install algoesup and ruff in their env and share essay on VLE forums.
[ ] Test in Windows, Linux and macOS M269 environments, after #10 is fixed.

mwermelinger commented 8 months ago

@densnow I've started a new branch m269-guide, based on the current main, for this. Could you please check that the instructions work for the m269-23j environment, where students have allowed locally via an alias, and not via pip?

I haven't yet generated the docs, I'm using just mkdocs serve for the moment.

The way to download the template is clunky at the moment (requires right-click). I thought of linking to GH to then click on the download button but the GH UI can be intimidating. Any suggestions welcome.

Feel free to add detail to the instructions. Thanks.

densnow commented 8 months ago

@mwermelinger The aliased allowed does not seem to be picked up by %allowed. Even though the shell=true arg is set, the shell config file is still bypassed AFAIK.

mwermelinger commented 8 months ago

Well, since allowed can check a whole notebook, it's not crucial to run it from within the notebook, but the documentation will have to say that. The allowed on command checks the cell it's in, so at that point there should be a message if the linter can't be run.

densnow commented 8 months ago

If a student (that already had the allowed alias in their shell config) installed allowed via pip, I think the alias would continue to work for them, but the %allowed magic would use the PYPI version of allowed.

mwermelinger commented 8 months ago

Good idea, will check it tomorrow on macOS. If you could test on Linux and Windows would be good.

densnow commented 8 months ago

Yes, will test that to make sure.

The allowed on command checks the cell it's in, so at that point there should be a message if the linter can't be run.

When the commands that are used by the magics were not found (because the package was not installed), it was only %ruff that printed an error message and the message was obscure. %allowed and %pytype did not print anything to indicate that the command was not found.

I think all three magics could benefit from better error handling including clearer messaging. This issue could be grouped together with #8 if we make the title and description more generic?

mwermelinger commented 8 months ago

@densnow I've updated the m269 guide (pyproject.toml needs to be downloaded too) and tested on macOS. Over to you. If it works on Linux and Windows, please do

[x] poetry run mkdocs build which will change all files because the nav panel has a new entry
[x] push the docs
[ ] squash and merge this branch into main, with a commit msg Fix #11: add M269 start guide

Thanks

densnow commented 8 months ago

@mwermelinger We have a bug with the %allowed magic on Windows. It is not related to having both local and PyPi versions of allowed, but has to do with Windows paths and the way \U from \Users is interpreted in the command line (as escape sequence) :upside_down_face: .

I will have to open a separate issue for this bug.

mwermelinger commented 8 months ago

If it's an independent issue, best to first do the three tasks above to close this issue, and then work on #16.