minor docs update (#56)

* add specific step for checking post-install tasks

* typos and clarifications

* more info on remote-specific .gitconfig

* bump gh actions versions

* add additional site to exclude from linkchecks

.github/workflows/docs.yml

@@ -12,7 +12,7 @@ jobs:
   build-docs:
     runs-on: "ubuntu-latest"
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: build env
       run: |
@@ -56,7 +56,7 @@ jobs:
         touch /tmp/doc/.nojekyll
 
     - name: push artifact
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: doc
         path: /tmp/doc

docs/conf.py

@@ -75,4 +75,5 @@
 linkcheck_ignore = [
     r'https://apple.stackexchange.com',
     r'https://stackoverflow.com',
+    r'www.gnu.org/software',
 ]

docs/post.rst

@@ -1,3 +1,5 @@
+.. _postinstall:
+
 Post-setup tasks
 ================
 
@@ -38,9 +40,9 @@ beginning/end of a *document* rather than a *line*. This is different from the
 Windows and Linux behavior of jumping to beginning/end of a line.
 
 The typical workaround is to use Cmd-Left and Cmd-Right. Some programs (like
-Outlook on Mac) already override this. But some don't, noticeable web browsers.
+Outlook on Mac) already override this. But some don't, like web browsers.
 When editing a large text input box in a web browser, it can be frustrating if
-you mistakenly hit End, expecting to jump to the end of a like in Outlook, but
+you mistakenly hit End, expecting to jump to the end of a line in Outlook, but
 instead it jumps to the very end of the text input and you have to go find where you were.
 
 Running ``./setup.sh --mac-keyboard-fix`` fixes this by creating a new
@@ -58,14 +60,15 @@ systems which typically default to bash as well). See `this post
 <https://apple.stackexchange.com/a/361957>`_ for a great explanation of the
 differences. 
 
-The ``chsh`` command just has to be run once to change the shell to bash. To
-avoid the message about zsh popping up all the time (as `documented at
-support.apple.com <https://support.apple.com/en-us/HT208050>`_), set
+The ``chsh`` command just has to be run once to change the shell to bash. But
+the warning will still show up. To avoid the message about zsh popping up all
+the time (as `documented at support.apple.com
+<https://support.apple.com/en-us/HT208050>`_), set
 ``BASH_SILENCE_DEPRECATION_WARNING=1``. Here, we export it in :file:`~/.extra`,
 which as :ref:`bashrc` describes, will be sourced by :file:`.bashrc` once these
 dotfiles are set up.
 
-.. code-block::
+.. code-block:: bash
 
     chsh -s /bin/bash
     echo "export BASH_SILENCE_DEPRECATION_WARNING=1" >> ~/.extra
@@ -114,7 +117,7 @@ exist). Then, by using the ``s`` alias, your SSH key will be added to the
 session using your login to MacOS as the authentication, without needing to
 type in your passphrase
 
-.. code-block::
+.. code-block:: bash
 
     # this goes in ~/.ssh/config
     Host *
@@ -125,11 +128,46 @@ type in your passphrase
 Git config
 ----------
 
+Setting up git is important for your commits to be attributed to you.
+
 .. code-block:: bash
 
     git config --global user.name "your name here"
     git config --global user.email "your email here"
 
+
+Alternatively you can edit :file:`~/.gitconfig` to add:
+
+.. code-block:: ini
+
+   [user]
+       name = "your name here"
+       email = "your email here"
+
+Optionally, you can conditionally include other files. This is useful, for
+example, if you have different emails configured for different remotes (GitHub,
+GitLab):
+
+.. code-block:: ini
+
+   # In main .gitconfig, this will be the default...
+   [user]
+       name = "your name here"
+       email = "your email here"
+
+   # ...unless the configured SSH remote matches "[email protected]:*/**"
+   [includeIf "hasconfig:remote.*.url:[email protected]:*/**"]
+       # ...in which case this file will be included verbatim
+       path = .gitlab.inc
+
+.. code-block:: ini
+
+   # In .gitlab.inc
+   [user]
+       # Override the email
+       email = "your OTHER email here"
+
+
 Alacritty config
 ----------------
 If you're using Alacritty as your terminal, it needs a little configuration to

docs/starthere.rst

@@ -252,9 +252,15 @@ details on how to activate environments.
     <https://bioconda.github.io>`_.
 
 
+3: Post-installation
+--------------------
+
+Now that the files are copied, see :ref:`postinstall` for some next steps to
+take, like setting up SSH keys, macOS-specific tweaks, git config, and more.
+
 .. _toolsection:
 
-3: Installing programs
+4: Installing programs
 ----------------------
 
 The :file:`setup.sh` script has many commands for installing various tools