From f17d2458970eef533c9c706b0cd0b9f98c8e581e Mon Sep 17 00:00:00 2001 From: Tim Mensinger Date: Wed, 2 Oct 2024 21:18:34 +0200 Subject: [PATCH] Update Python installation instructions in docs (#162) --- .github/workflows/main.yml | 1 + .pre-commit-config.yaml | 6 +- docs_template/source/faq.md | 74 +++++-------------- .../getting_started/preparing_your_system.md | 31 ++++---- .../source/getting_started/second_machine.md | 2 +- .../guides_explanations/environments.md | 3 +- inst/WORDLIST | 3 + pyproject.toml | 3 + 8 files changed, 48 insertions(+), 75 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 81837cda..59169535 100644 --- a/.github/workflows/main.yml +++ b/.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: | diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b7d217d6..6139aa01 100644 --- a/.pre-commit-config.yaml +++ b/.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] diff --git a/docs_template/source/faq.md b/docs_template/source/faq.md index 3474ec95..703b69d7 100644 --- a/docs_template/source/faq.md +++ b/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/" ``` diff --git a/docs_template/source/getting_started/preparing_your_system.md b/docs_template/source/getting_started/preparing_your_system.md index ee6512b8..c1cc1d69 100644 --- a/docs_template/source/getting_started/preparing_your_system.md +++ b/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 diff --git a/docs_template/source/getting_started/second_machine.md b/docs_template/source/getting_started/second_machine.md index 9d6b67ae..18d90f92 100644 --- a/docs_template/source/getting_started/second_machine.md +++ b/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 diff --git a/docs_template/source/guides_explanations/environments.md b/docs_template/source/guides_explanations/environments.md index ead5bfb7..2310cb15 100644 --- a/docs_template/source/guides_explanations/environments.md +++ b/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 diff --git a/inst/WORDLIST b/inst/WORDLIST index 361262bd..98436d42 100644 --- a/inst/WORDLIST +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 4c159146..279c70e7 100644 --- a/pyproject.toml +++ b/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]