diff --git a/.gitignore b/.gitignore index cc491f4..a5d7794 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ hku-logo-xs.png .workspace/ .codebuddy/ .vscode -.idea \ No newline at end of file +.idea +assets/.DS_Store diff --git a/.workbuddy/memory/2026-08-10.md b/.workbuddy/memory/2026-08-10.md new file mode 100644 index 0000000..8bfe2fe --- /dev/null +++ b/.workbuddy/memory/2026-08-10.md @@ -0,0 +1,43 @@ +# 2026-08-10 β€” conda-first install guide + git recovery incident + +## Project +`python-setup-moodle` β€” beginner Python install tutorial (English prose, Chinese UI chat). +Convention (AGENTS.md): emoji callouts (πŸ“πŸ’‘βš οΈβ—) instead of GitHub alert syntax; no authoring +instructions in reader-facing `.md`; commands split per OS, no copyable `$`. + +## install guide content decisions (this session) +- Reorder: **conda first (Method A, most recommended)**, **uv second (Method B)**, standalone third. +- Anaconda vs Miniconda: documented as two conda distributions (differ only in pre-installed + packages; full Anaconda ~3GB, Miniconda minimal). "conda" command identical for both. +- Install now requires **concrete versions** (not "latest"). Anaconda example Anaconda3-2026.07-1. +- Course env = **`mffintech`** (cloned from base): out-of-box Python 3.14.6 / NumPy 2.4.6 / + pandas 3.0.3 / PyArrow 23.0.1 / pytest 9.0.3 / JupyterLab 4.5.9. Extra: duckdb=1.5.4, + polars=1.43.2, yfinance=1.5.2. +- **conda rule:** prefer `conda install` over `pip` inside conda envs (pip pkgs invisible to conda). +- uv: must `cd` into project before `uv pip install`/`uv run` or it pollutes `~/.venv` in home. +- Section order: test β†’ Run your first program β†’ **How to debug** (debug moved to very end). + +## ⚠️ GIT REPO IS FRAGILE β€” read before any git op +- During a PR attempt the repo got corrupted. `main` ref now = `08aa301` (origin/base, the + published Aug-5 version). `HEAD` currently points to branch `docs/ide-setup-cdn-images`. +- A dangling root commit `0235d60` exists but its tree is broken at the `pages` subtree + (object `ad15a881` missing) β†’ cannot extract files from it. +- Loose blob `477f05` = an *intermediate* installation.md (has conda-first + πŸ“ note, but + missing mffintech/pkg-table/conda-install/Miniconda-links/heading-restructure/uv-warning). +- **Do NOT run `git commit`/`checkout -f`/`switch` casually here** β€” earlier a `checkout -f main` + reverted installation.md, virtual-environment.md AND AGENTS.md to base (lost all our edits). + +## Recovery status (end of session) +- `pages/installation.md`: **REBUILT** (conda-first, mffintech env, pkg table, conda-install + pref, Miniconda links, heading restructure, uv cd warning, debug-at-end). NOT touched again. +- `pages/virtual-environment.md`: **REBUILT this turn** (full Write). Re-ordered conda+Channels + BEFORE uv; added Anaconda vs Miniconda comparison table; fixed Channels to "prefer conda + install over pip"; added uv `requirements.txt` 2nd method + cd warning; ending πŸ’‘ now + recommends **conda (Miniconda)**. +- `AGENTS.md`: **REBUILT this turn** (3 Edits). "why conda is preferred (uv as fast + alternative)"; conda listed before uv; "specific, concrete versions" (no "latest"); with + conda split into **Anaconda + Miniconda** two distributions, each with verified install-doc + URLs (mac-cli-install / windows-cli-install / linux-install). +- Verified Anaconda install-doc URLs via WebFetch: mac-cli-install βœ“, windows-cli-install βœ“, + linux-install βœ“. (mac-os-install / mac-install / windows-install all 404.) +- Temp/backup files created during recovery were deleted; `.bak.tar.gz` removed. diff --git a/AGENTS.md b/AGENTS.md index 2f83111..ccd9489 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,14 +70,13 @@ Options and arguments (and corresponding environment variables): - why executables on windows has `exe` extension and why unix does not have - pwsh commands: unix-like aliases and its original commands and why windows is not prefered. e.g. `Get-Command` = `which` ### (short, non-compulsory)concept of virtual enviroment -- why need virtual env rather than standalone python, why uv is prefered. why /usr/bin/python3 cannot be used directly -- uv +- why need virtual env rather than standalone python, why conda is preferred (uv as a fast alternative). why /usr/bin/python3 cannot be used directly - conda:https://www.anaconda.com/docs/getting-started/concepts/anaconda-or-miniconda -- anaconda -- miniconda, difference of channels, conda-forge and others +- anaconda (full distribution: conda + 250+ pre-installed packages, ~3 GB) and miniconda (minimal installer: conda only, ~100 MB), difference of channels, conda-forge and others +- uv:https://docs.astral.sh/uv/ (fast alternative) - difference of `conda` and `uv`, `conda activate` vs `source .venv/bin/activate`, global vs local enviroment ### (very detail) How to installation python executable -- how to choose version (amd64, arm64, x86_64, exe) and how to set up first python enviroment +- how to choose **specific, concrete versions** β€” a fixed Python version (e.g. 3.12), the exact CPU arch (amd64, arm64, x86_64, aarch64), and the exact installer version number for Anaconda/Miniconda. Never write "latest" or leave the version blank. Then how to set up first python enviroment - standalone installation, double click exe to install - win: - https://www.python.org/downloads/windows/ @@ -91,14 +90,18 @@ Options and arguments (and corresponding environment variables): - with standalone installer:https://www.python.org/downloads/source/ - typecially it will be installed under the path of -- with conda: - - url: - - macos:https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install#using-miniconda-in-a-commercial-setting - - windows:https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install#powershell - - linux:https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install#installation-steps - - how to install - - introduce cli reference`conda create --name py310 python=3.12` - - `conda activate ` condaand how to re-activate after close terminal +- with conda (two distributions β€” pick one): + - **Anaconda** (full distribution: conda + 250+ pre-installed packages, ~3 GB) β€” official install docs: + - macos: https://www.anaconda.com/docs/getting-started/anaconda/install/mac-cli-install + - windows: https://www.anaconda.com/docs/getting-started/anaconda/install/windows-cli-install + - linux: https://www.anaconda.com/docs/getting-started/anaconda/install/linux-install + - **Miniconda** (minimal installer: conda only, no pre-installed packages β€” recommended) β€” official install docs: + - macos: https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install + - windows: https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install + - linux: https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install + - how to install (same for both distributions) + - introduce cli reference `conda create --name py310 python=3.12` + - `conda activate ` and how to re-activate after close terminal - how to set specific pre-installed python executable for new env to save space - with uv: - url: https://docs.astral.sh/uv/getting-started/installation/#pypi diff --git a/build_release.py b/build_release.py index fc6503a..9adaa92 100644 --- a/build_release.py +++ b/build_release.py @@ -22,11 +22,10 @@ Requires: Python 3.8+, the `markdown` package. -TODO: image references in the release still point to the local relative path -(`../assets/img/...`) as produced by the Markdown. Before publishing, rewrite -these to GitHub permalinks (e.g. -`https://github.com/fyq163/python-setup-moodle/raw/main/assets/img/...`) so the -release needs no bundled `assets/` folder. This step is done manually. +Image handling in the release build: any image whose URL is already an absolute +`https://` link is kept as-is, while local repo-relative paths (`../assets/img/...`) +are rewritten to a public CDN URL. So the release output is fully self-contained +and needs no bundled `assets/` folder. """ import os import re @@ -76,8 +75,20 @@ def slugify(s): def render_body(md_text): """Render markdown to HTML and add heading ids / collect a TOC.""" html = _md.markdown(md_text, extensions=MD_EXTENSIONS) - # TODO: image src still uses the local relative path (`../assets/img/...`). - # Rewrite to a GitHub permalink before publishing (see file header). + # Rewrite ONLY local repo-relative image paths (../assets/img/...) to a + # public URL. Images that already use an absolute https:// URL are left + # untouched ("detect https -> skip; detect repo path -> render"). + GITHUB_CDN = "https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main" + + def _rewrite_img(mo): + src = mo.group(1) + if src.startswith("https://"): + return mo.group(0) # already public -> keep as-is + if src.startswith("../assets/img/"): + return 'src="%s/assets/img/%s"' % (GITHUB_CDN, src[len("../assets/img/"):]) + return mo.group(0) # other relative path -> leave alone + + html = re.sub(r'src="([^"]+)"', _rewrite_img, html) # Turn any leftover GitHub-style alert markers into emoji callouts. html = re.sub( r'
\s*

\s*\[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\s*', @@ -261,7 +272,6 @@ def main(): with open(os.path.join(OUT, name + ".html"), "w", encoding="utf-8") as f: f.write(out) print("built release/%s.html" % name) - # No local assets/ folder: release references images via GitHub permalink. print("release build complete -> %s" % OUT) diff --git a/pages/ide-setup.md b/pages/ide-setup.md index aef3a88..3be1a37 100644 --- a/pages/ide-setup.md +++ b/pages/ide-setup.md @@ -18,27 +18,35 @@ identical: 4. Select the interpreter: press `Ctrl/Cmd + Shift + P`, type **"Python: Select Interpreter"**, and choose the environment you made in Chapter 3 (the `.venv` or conda env). The bottom-right status bar then shows that Python. + ![vscode plugin marketplace](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/vscode-extension-python.png) 5. Use the built-in terminal (`Ctrl/Cmd + `` `) to run `uv run main.py` or `python main.py`. - -![TODO: Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](../assets/img/placeholder.svg) +![Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/vscode-interpreter-selection.png) > πŸ’‘ > Once the interpreter is selected, the play button (β–Ά) and the terminal both use *your* > project's Python β€” not the system one. That is the whole point. -## PyCharm Community Edition +## PyCharm + +> ❗ +> Since 2025, JetBrains has **merged the Community and Professional editions** of PyCharm +> into a single product. The **basic features are free to use**; the **advanced features +> require a paid subscription**. As a student, you can get that subscription for free via +> the [JetBrains Student Pack](https://www.jetbrains.com/academy/student-pack/) β€” sign in +> with your school email and the advanced features unlock at no cost. -PyCharm is a Python-focused IDE with a free **Community** edition (the **Professional** -edition adds web/DB features and is paid, though free for students). +PyCharm is a Python-focused IDE. The **basic features** (editing, running, debugging Python) +are free; the **advanced features** (web frameworks, database tools, etc.) need a +subscription, which students get free with the Student Pack above. -1. Download [PyCharm Community](https://www.jetbrains.com/pycharm/download/). +1. Download [PyCharm](https://www.jetbrains.com/pycharm/download/). 2. **New Project** β†’ choose a location. Under "Python Interpreter", select **Previously configured interpreter** and point it at your `conda` env or the `python` inside `.venv/bin` (macOS/Linux) / `.venv\Scripts\python.exe` (Windows). Or let PyCharm create a new `venv` for you. 3. Right-click a `.py` file and choose **Run**. - +- ![PyCharm change interpreter](https://pub-639e92bd227c4441a00a10db2a268512.r2.dev/image/GitHub-pages/python-install/pycharm-interpreter-selection.png) References: [PyCharm + conda](https://www.anaconda.com/docs/getting-started/working-with-conda/ides/pycharm), [Python path](https://www.anaconda.com/docs/getting-started/working-with-conda/ides/python-path) @@ -57,4 +65,3 @@ Python your shell currently has active. GitHub Copilot is an AI pair-programmer that suggests code as you type. **Students get it free** (and many other developer tools) through the [GitHub Copilot - Information Technology Services - HKU](https://its.hku.hk/software/github-copilot/) -pack with a school email. \ No newline at end of file diff --git a/pages/installation.md b/pages/installation.md index 93563fc..faf531f 100644 --- a/pages/installation.md +++ b/pages/installation.md @@ -3,8 +3,8 @@ title: 3 Β· Installing Python tag: Required --- -The detailed chapter. Three methods (standalone / conda / uv) Γ— three platforms (macOS -arm64, Windows amd64, Linux x86_64). **Pick one method** β€” we recommend **uv** for +The detailed chapter. Three methods (conda / uv / standalone) Γ— three platforms (macOS +arm64, Windows amd64, Linux x86_64). **Pick one method** β€” we recommend **conda** for beginners. You only need Python installed once per machine. ## How to choose a version & architecture @@ -16,65 +16,116 @@ beginners. You only need Python installed once per machine. - **macOS:** Apple Silicon Macs (M1/M2/M3/M4) β†’ **arm64**. Intel Macs β†’ **x86_64**. - **Windows:** almost all modern PCs β†’ **amd64** (also called x64). - **Linux:** most desktops/servers β†’ **x86_64**; newer ARM boards β†’ **aarch64**. +> πŸ“ The guide below shows one standard installation. This course will teach using this +> version as the reference, but you are always free to choose your own way to install +> based on your needs. -If you are unsure, the installer pages below usually auto-detect the right one. +## Method A Β· With conda (most recommended) -> **⚠️ Choose a Stable Release (all methods & platforms).** Whether you use the standalone -> installer, conda, or uv, pick a **Stable Release** β€” the latest stable version (e.g. -> Python 3.12.x or 3.13.x). **Do not** download or install anything marked *Pre-release* or -> *Development*: those builds are for testing and may be unstable or break your packages. +Best for beginners: one environment manager that also handles data-science and +non-Python system dependencies (CUDA, R, …). -## Method A Β· With uv (most recommended) +### Install Conda. -Best for beginners: one fast tool, local environments, minimal fuss. +#### Standard Anaconda Installation -1. Install uv. Open the uv website (docs.astral.sh/uv) in your browser, go to the - **Installation** page, and download the installer for your system (macOS, Windows, or - Linux). Run it and follow the on-screen prompts β€” pick the default options when asked. - When it finishes, uv is installed. +##### Windows: Anaconda Windows 64-bit -> πŸ“ After install, **close the terminal and open a new one**, then verify with `uv --version`. +1. download the installer + ```powershell + Invoke-WebRequest -Uri "https://repo.anaconda.com/archive/Anaconda3-2026.07-1-Windows-x86_64.exe" -OutFile ".\Anaconda3-2026.07-1-Windows-x86_64.exe" + ``` + **Alternatively**, download the installer from the url and change directory to the location where it was downloaded, then double click it to run. +2. Then **double click it to run installation**. -2. Install a Python and create your first project: +##### macOS -```bash -uv python install 3.12 # download CPython 3.12 (one time) -uv init myproject # create a project folder with a .venv -cd myproject -uv pip install pandas # install a package into this project -uv run main.py # run a script with this project's Python -``` + ```bash + curl -O https://repo.anaconda.com/archive/Anaconda3-2026.07-1-MacOSX-arm64.sh + bash ./Anaconda3-2026.07-1-MacOSX-arm64.sh + ``` + > **Alternatively**, download the installer from the url and change directory to the location where it was downloaded, then paste it's path in the terminal and run it with `bash `. + > ⚠️ If you have an *Intel Mac*, see below for miniconda option, anaconda has stopped supporting Intel Macs. -- **After closing the terminal**, you do **not** need to "activate" β€” just run - `uv run