From 78c92cc766154f56d3866d418c33278454fd7505 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Tue, 2 Nov 2021 20:38:06 +0100
Subject: [PATCH] Address common issues with load path configuration in docs
 (#5356)

* Add instructions on how to add pyenv to load path

* Support zsh in pyenv load path instructions

* Make instructions for Mac work when shell-specific profile file exists

* Includes are weird...

* .

* Fix my misunderstanding of what files zsh sources

* Operator precedence, or something like that
---
 .../_install-pyenv-and-setup-path.rst         | 19 +++++++++++++++++++
 .../_includes/install-python-pyenv.rst        |  9 +--------
 .../_includes/install-python38-pyenv.rst      |  9 +--------
 docs/install_guides/mac.rst                   | 11 +++++++++--
 4 files changed, 30 insertions(+), 18 deletions(-)
 create mode 100644 docs/install_guides/_includes/_install-pyenv-and-setup-path.rst

diff --git a/docs/install_guides/_includes/_install-pyenv-and-setup-path.rst b/docs/install_guides/_includes/_install-pyenv-and-setup-path.rst
new file mode 100644
index 000000000..b3f0f4d38
--- /dev/null
+++ b/docs/install_guides/_includes/_install-pyenv-and-setup-path.rst
@@ -0,0 +1,19 @@
+To install/update pyenv, run the following command:
+
+.. prompt:: bash
+
+    command -v pyenv && pyenv update || curl https://pyenv.run | bash
+
+After this command, you will see a warning about 'pyenv' not being in the load path. To address this,
+you should run these commands:
+
+.. prompt:: bash
+
+    profile=$([ -n "$ZSH_VERSION" ] && echo ~/.zprofile || ([ -f ~/.bash_profile ] && echo ~/.bash_profile || echo ~/.profile))
+    rcfile=$([ -n "$ZSH_VERSION" ] && echo ~/.zshrc || echo ~/.bashrc)
+    printf '%s\n%s\n%s\n' 'export PYENV_ROOT="$HOME/.pyenv"' 'export PATH="$PYENV_ROOT/bin:$PATH"' "$([ -f "$profile" ] && cat "$profile")" > "$profile"
+    echo 'eval "$(pyenv init --path)"' >> "$profile"
+    echo 'eval "$(pyenv init -)"' >> "$rcfile"
+    echo 'eval "$(pyenv virtualenv-init -)"' >> "$rcfile"
+
+Then **log out and log back in** and run the following command:
diff --git a/docs/install_guides/_includes/install-python-pyenv.rst b/docs/install_guides/_includes/install-python-pyenv.rst
index c020ee468..f05aa5517 100644
--- a/docs/install_guides/_includes/install-python-pyenv.rst
+++ b/docs/install_guides/_includes/install-python-pyenv.rst
@@ -6,14 +6,7 @@ On distributions where Python 3.9 needs to be compiled from source, we recommend
 This simplifies the compilation process and has the added bonus of simplifying setting up Red in a
 virtual environment.
 
-.. prompt:: bash
-
-    command -v pyenv && pyenv update || curl https://pyenv.run | bash
-
-**After this command, you may see a warning about 'pyenv' not being in the load path. Follow the
-instructions given to fix that, then close and reopen your shell.**
-
-Then run the following command:
+.. include:: _includes/_install-pyenv-and-setup-path.rst
 
 .. prompt:: bash
 
diff --git a/docs/install_guides/_includes/install-python38-pyenv.rst b/docs/install_guides/_includes/install-python38-pyenv.rst
index ae72c622b..f48314868 100644
--- a/docs/install_guides/_includes/install-python38-pyenv.rst
+++ b/docs/install_guides/_includes/install-python38-pyenv.rst
@@ -6,14 +6,7 @@ On distributions where Python 3.8 needs to be compiled from source, we recommend
 This simplifies the compilation process and has the added bonus of simplifying setting up Red in a
 virtual environment.
 
-.. prompt:: bash
-
-    command -v pyenv && pyenv update || curl https://pyenv.run | bash
-
-**After this command, you may see a warning about 'pyenv' not being in the load path. Follow the
-instructions given to fix that, then close and reopen your shell.**
-
-Then run the following command:
+.. include:: _includes/_install-pyenv-and-setup-path.rst
 
 .. prompt:: bash
 
diff --git a/docs/install_guides/mac.rst b/docs/install_guides/mac.rst
index d2c07d5cc..e5c49d075 100644
--- a/docs/install_guides/mac.rst
+++ b/docs/install_guides/mac.rst
@@ -22,11 +22,18 @@ one-by-one:
 .. prompt:: bash
 
     brew install python@3.9
-    echo 'export PATH="$(brew --prefix)/opt/python@3.9/bin:$PATH"' >> ~/.profile
-    source ~/.profile
     brew install git
     brew install --cask adoptopenjdk/openjdk/adoptopenjdk11
 
+By default, Python installed through Homebrew is not added to the load path.
+To fix this, you should run these commands:
+
+.. prompt:: bash
+
+    profile=$([ -n "$ZSH_VERSION" ] && echo ~/.zprofile || ([ -f ~/.bash_profile ] && echo ~/.bash_profile || echo ~/.profile))
+    echo 'export PATH="$(brew --prefix)/opt/python@3.9/bin:$PATH"' >> "$profile"
+    source "$profile"
+
 .. Include common instructions:
 
 .. include:: _includes/create-env-with-venv.rst