Update Python installation instructions in docs (#162)

.github/workflows/main.yml

@@ -34,6 +34,7 @@ jobs:
           environment-file: environment.yml
           create-args: python=${{ matrix.python-version }}
           cache-environment: true
+          micromamba-version: 1.5.6-0
       - name: Run full test suite on MacOS and Linux
         shell: bash -l {0}
         run: |

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
       # - id: check-hooks-apply  # Leave nbqa in here.
       # - id: identity  # Prints all files passed to pre-commits. Debugging.
   - repo: https://github.com/lyz-code/yamlfix
-    rev: 1.16.0
+    rev: 1.17.0
     hooks:
       - id: yamlfix
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -37,7 +37,7 @@ repos:
     hooks:
       - id: yamllint
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.1
+    rev: v0.6.8
     hooks:
       # Run the linter.
       - id: ruff
@@ -75,7 +75,7 @@ repos:
 
   # R specific hooks: https://github.com/lorenzwalthert/precommit
   - repo: https://github.com/lorenzwalthert/precommit
-    rev: v0.4.3
+    rev: v0.4.3.9001
     hooks:
       - id: style-files
         args: [--style_pkg=styler, --style_fun=tidyverse_style]

docs_template/source/faq.md

@@ -6,43 +6,6 @@
 
 ## Tips and Tricks for Windows Users
 
-**Anaconda Installation Notes for Windows Users**
-
-Please follow these steps unless you know what you are doing.
-
-1. Download the [Graphical Installer](https://www.anaconda.com/products/distribution)
-   for Python 3.x.
-
-1. Start the installer and click yourself through the menu. If you have administrator
-   privileges on your computer, it is preferable to install Anaconda for all users.
-   Otherwise, you may run into problems when running python from your powershell.
-
-1. Make sure to (only) tick the following box:
-
-   - ''Register Anaconda as my default Python 3.x''. Finish installation.
-
-1. Navigate to the folder containing your Anaconda distribution. This folder contains
-   multiple subfolders. Please add the path to the folder called `condabin` to your
-   *PATH* environmental variable. This path should end in `Anaconda3/condabin`. You can
-   add paths to your *PATH* by following these
-   [instructions](https://www.computerhope.com/issues/ch000549.htm).
-
-1. Please start Windows Powershell in administrator mode, and execute the following:
-
-   ```bash
-   $ set-executionpolicy remotesigned
-   ```
-
-1. Now (re-)open Windows Powershell and initialize it for full conda use by running
-
-   ```bash
-   $ conda init
-   ```
-
-```{warning} If you still run into problems when running conda and python from
-powershell, it is advisable to use the built-in Anaconda Prompt instead.
-```
-
 (git_windows)=
 
 ### Integrating git tab completion in Windows Powershell
@@ -64,38 +27,41 @@ how to do that.
 
 ### Adding directories to the PATH: MacOS and Linux
 
-Open the program **Terminal**. You will need to add a line to the file `.bash_profile`
-and potentially create the file. This file lives in your home directory, in the Finder
-it is hidden from your view by default.
+Open the program **Terminal**. First, you will need to determine the shell you are
+using:
+
+```zsh
+echo $SHELL
+```
 
-**Linux users**: For most distributions, everything here applies to the file `.bashrc`
-instead of `.bash_profile`.
+The output will be something like `/bin/bash` or `/bin/zsh`. Depending on the output,
+the below applies either to the file `.bashrc` or `.zshrc`. Both of them live in your
+home directory and are read every time you open a new terminal.
 
-I will now provide a step-by-step guide of how to create / adjust this file using the
-editor called `code`. If you are familiar with editing text files, just use your editor
-of choice.
+I will now provide a step-by-step guide of how to create / adjust the file `.zshrc`
+using the editor [VS Code](https://code.visualstudio.com/), which you can typically
+start from a shell by typing `code`. If you are familiar with editing text files, just
+use your editor of choice. If you are using a `bash` shell, replace `.zshrc` with
+`.bashrc` in the following.
 
 1. Open a Terminal and type
 
-   ```bash
-   code ~/.bash_profile
+   ```zsh
+   code ~/.zshrc
    ```
 
-   If you use an editor other than [VS Code](https://code.visualstudio.com/), replace
-   `code` by the respective editor.
-
-   If `.bash_profile` already existed, you will see some text at this point. If so, use
-   the arrow keys to scroll all the way to the bottom of the file.
+   If `.zshrc` already existed, you will see some text at this point. If so, use the
+   arrow keys to scroll all the way to the bottom of the file.
 
 1. Add the following line at the end of the file
 
-   ```bash
+   ```zsh
    export PATH="${PATH}:/path/to/program/inside/package"
    ```
 
    You will need to follow the same steps as before. Example for Stata:
 
-   ```bash
+   ```zsh
    # Stata directory
    export PATH="${PATH}:/Applications/Stata/StataMP.app/Contents/MacOS/"
    ```

docs_template/source/getting_started/preparing_your_system.md

@@ -3,14 +3,14 @@
 Make sure you have the following programs installed and that these can be found on your
 path. This template requires
 
-- [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or
-  [Micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) or
-  Anaconda. Windows users: please consult {ref}`windows_user`
+- Python, which you must install using the following instructions
 
-  ```{note} This template is tested with python 3.12 and higher and conda 24.5
-  ```
+  - [Installing Python on Mac](https://effective-programming-practices.vercel.app/python_installation_execution/installation_mac/instructions.html)
+  - [Installing Python on Windows](https://effective-programming-practices.vercel.app/python_installation_execution/installation_windows/instructions.html)
+  - [Installing Python on WSL (for the adventurous)](https://effective-programming-practices.vercel.app/python_installation_execution/installation_wsl/instructions.html)
+  - [Installing Python on Linux](https://effective-programming-practices.vercel.app/python_installation_execution/installation_linux/instructions.html)
 
-- a modern LaTeX distribution (e.g. [TeXLive](https://tug.org/texlive/),
+- A modern LaTeX distribution (e.g. [TeXLive](https://tug.org/texlive/),
   [MacTex](https://tug.org/mactex/), or [MikTex](https://miktex.org/))
 
 - [Git](https://git-scm.com/downloads), Windows users please also consult
@@ -23,10 +23,10 @@ path. This template requires
 
 If you are on Windows, please open the Windows Powershell. On Mac or Linux, open a
 terminal. As everything will be started from the Powershell/Terminal, you need to make
-sure that all programmes you need in your project (for sure Anaconda Python, Git, and
-LaTeX; potentially VS Code, R, Julia, Stata) can be found on your *PATH*. That is, these
-need to be accessible from your shell. This often requires a bit of manual work, in
-particular on Windows.
+sure that all programmes you need in your project (for sure Python obtained via
+Miniforge, Git, and LaTeX; potentially VS Code, R, Julia, Stata) can be found on your
+*PATH*. That is, these need to be accessible from your shell. This often requires a bit
+of manual work, in particular on Windows.
 
 - To see which programmes can be found on your path, type (leave out the leading dollar
   sign, this is just standard notation for a command line prompt):
@@ -46,10 +46,11 @@ particular on Windows.
   This gives you a list of directories that are available on your *PATH*.
 
 - Check that this list contains the path to the programs you want to use in your
-  project, in particular, Anaconda (this contains your Python distribution), a LaTeX
-  distribution, the text editor VS Code, Git, and any other program that you need for
-  your project (R, Julia, Stata). Otherwise add them by looking up their paths on your
-  computer and follow the steps described here {ref}`path_windows` or {ref}`path_mac`.
+  project, in particular, Miniforge (this contains the required Python distribution), a
+  LaTeX distribution, the text editor VS Code, Git, and any other program that you need
+  for your project (R, Julia, Stata). Otherwise, add them by looking up their paths on
+  your computer and follow the steps described here {ref}`path_windows` or
+  {ref}`path_mac`.
 
 - If you added any directory to *PATH*, you need to close and reopen your shell, so that
   this change is implemented.
@@ -63,7 +64,7 @@ particular on Windows.
   ```
 
   This starts python in your shell and exits from it again. The top line should indicate
-  that you are using a Python distribution provided by Anaconda. Here is an example
+  that you are using a Python distribution provided by conda-forge. Here is an example
   output obtained on Linux:
 
   ```text

docs_template/source/getting_started/second_machine.md

@@ -3,7 +3,7 @@ very easy to invite a collaborator or to use a second machine. Importantly you d
 need to create the template repository again.
 
 On the second machine prepare the system and open a terminal on Mac/Linux or the
-Anaconda prompt on Windows. Then type
+Powershell on Windows. Then type
 
 ```console
 $ git clone <url_of_your_repository>

docs_template/source/guides_explanations/environments.md

@@ -8,8 +8,7 @@ The solution is to have isolated environments on a per-project basis.
 allow you to do precisely this. This page describes them a little bit and explains their
 use.
 
-The following commands can either be executed in a terminal or the Anaconda prompt
-(Windows).
+The following commands can either be executed in a terminal or the Powershell (Windows).
 
 ### Using the environment
 

inst/WORDLIST

@@ -1110,6 +1110,7 @@ iR
 IrqM
 Irt
 iS
+ISC
 iSL
 isort
 iT
@@ -1570,6 +1571,7 @@ mI
 Micromamba
 MikTex
 Miniconda
+Miniforge
 minimises
 mIw
 mj
@@ -2865,6 +2867,7 @@ Wsd
 WseQ
 wsj
 WSJ
+WSL
 wT
 wu
 wU

pyproject.toml

@@ -90,6 +90,9 @@ extend-ignore = [
     "D104",  # Missing docstring in public package (__init__.py files)
     "S301",  # pickle module is unsafe
     "PLR0913",  # Too many arguments in function definition
+    # ignore because conflict with ruff-format
+    "COM812",
+    "ISC001",
 ]
 
 [tool.ruff.lint.per-file-ignores]