Update bash config section and other maintenance (#32)

* Update sphinx & its extensions

Change to pin Sphinx version as recommended by readthedocs.
Install readthedocs extensions via pip because that's where they release
them. conda-forge release of sphinx-notfound-page has bee awaiting PR
review for over 2 weeks.

Update packages and versions used in recent writing env.
Noticed that cryptography and pyOpenSSL have been dropped as
dependencies.

* Update bash config section

re: possibility of default .bash_profile and .bashrc files on ocean
machines. Compstaff account setup process seems to have changed
during summer 2023 to include default files in new account $HOME.

* Update redirected links found by sphinx linkcheck

* Update readthedocs build config to mambaforge-22.9

* Install all dependencies from pip

That seems to be the only way to get a consistent collection of
dependencies with a version pin on Sphinx.

.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "mambaforge-4.10"
+    python: "mambaforge-22.9"
 
 conda:
   environment: environment.yaml

bash_config.rst

@@ -35,7 +35,7 @@ the output of that command will most likely be::
   /bin/bash
 
 In order to make :command:`bash` work well for us on the Waterhole workstations and other MOAD computers,
-we have to create two configuration files in our home directory:
+we have to create or edit two configuration files in our home directory:
 
 #. :file:`.bash_profile`
 #. :file:`.bashrc`
@@ -50,12 +50,16 @@ For quick reminders about some of the most often used Linux commands this `Unix
 
 .. _Create-.bash_profile:
 
-Create :file:`.bash_profile`
-============================
+Edit or Create :file:`.bash_profile`
+====================================
 
-New MOAD accounts on the Waterhole workstations are created completely empty.
+New MOAD accounts on the Waterhole workstations usually contain default versions 2 important configuration files,
+but sometimes those files are not created.
+:file:`.bash_profile` is one of those files.
 So,
-the first thing we need to do is create a file called `.bash_profile` in the home directory.
+the first thing we need to do is edit that file,
+or create it if it doesn't exist.
+:file:`.bash_profile` is stored in your home directory.
 Your home directory is the one that you land in when you :command:`ssh` to a remote computer,
 or when you start up a terminal session.
 
@@ -65,18 +69,20 @@ or when you start up a terminal session.
     You probably don't need to do this on your laptop because :file:`.bash_profile` likely already exists,
     and you shouldn't change it until you know what you are doing and why.
 
-Use the :command:`nano` text editor to create a new :command:`.bash_profile` file:
+Use the :command:`nano` text editor to open the :file:`.bash_profile` file:
 
 .. code-block:: bash
 
     $ nano .bash_profile
 
 The ``.`` at the beginning of the file name is important!
-Type,
-or copy/paste the following lines into the file:
+Ensure that the file contains the following lines:
 
 .. code-block:: bash
 
+    # .bash_profile
+
+    # Get the aliases and functions
     if [ -f "$HOME/.bashrc" ]; then
         . "$HOME/.bashrc"
     fi
@@ -103,27 +109,39 @@ It will come as no surprise that the next thing we are going to do is :ref:`Crea
 
 .. _Create-.bashrc:
 
-Create :file:`.bashrc`
-======================
+Edit or Create :file:`.bashrc`
+==============================
+
+The other important :command:`bash` configuration file is :file:`.bashrc`.
 
 .. note::
     You only need to do this once on the MOAD machines because you home directory is shared across all of the machines.
 
     You probably don't need to do this on your laptop because :file:`.bashrc` likely already exists.
     But if you like some of the aliases below you might want to add them to :file:`.bashrc` on your laptop.
 
-Use the :command:`nano` text editor to create a new :command:`.bashrc` file:
+Use the :command:`nano` text editor to open the :command:`.bashrc` file:
 
 .. code-block:: bash
 
     $ nano .bashrc
 
 The ``.`` at the beginning of the file name is important!
-Type,
-or copy/paste the following lines into the file:
+Ensure that the file contains the following lines:
 
 .. code-block:: bash
 
+    # .bashrc
+
+    # Source global definitions
+    if [ -f /etc/bashrc ]; then
+        . /etc/bashrc
+    fi
+
+    # Uncomment the following line if you don't like systemctl's auto-paging feature:
+    # export SYSTEMD_PAGER=
+
+    # User specific aliases and functions
     ## Environment variables
     # Shorter shell prompt
     PS1="\h:\W$ "

conda_pkg_env_mgr.rst

@@ -20,7 +20,7 @@ but we have found that using :program:`conda` and explicitly managing software e
 is more robust over time than using Anaconda.
 
 .. _Conda: https://docs.conda.io/en/latest/
-.. _Anaconda data science toolkit: https://www.anaconda.com/products/distribution
+.. _Anaconda data science toolkit: https://www.anaconda.com/download
 
 
 TODO: Write an intro to conda

environment.yaml

@@ -23,12 +23,14 @@ channels:
   - nodefaults
 
 dependencies:
-  - nbsphinx
-  - pip
   - python=3.11
-  - sphinx
-  - sphinx_rtd_theme=1.2
-  - sphinx-notfound-page
+  - pip
 
   # For repo QA
   - pre-commit
+
+  - pip:
+    - nbsphinx
+    - sphinx==7.2.5
+    - sphinx_rtd_theme
+    - sphinx-notfound-page

oceanparcels/index.rst

@@ -27,5 +27,5 @@ Useful links:
 .. _#oceanparcels Slack channel: https://salishseacast.slack.com/?redir=%2Farchives%2FC02ETTPHFPX
 .. _OceanParcels GitHub Discussion forum: https://github.com/OceanParcels/parcels/discussions
 .. _Ocean Sciences 2021 paper comparing OceanParcels and Ariane: https://os.copernicus.org/articles/17/1067/2021/
-.. _Advection kernels: https://parcels.readthedocs.io/en/latest/reference/predefined_kernels.html
+.. _Advection kernels: https://docs.oceanparcels.org/en/latest/reference/predefined_kernels.html
 .. _Ben's notebook: https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/OceanParcelsRecipes.ipynb

python_packaging/pkg_structure.rst

@@ -161,7 +161,8 @@ The sub-sections below describe the 6 files that are typically present in the to
 of our packages.
 Three of those files that *must* be present contain the information necessary to create a Python package:
 
-* :ref:`PyprojectTomlFile` that contains the build system requirements and build backend tools to use for creation of the package,
+* :ref:`PyprojectTomlFile` that contains the build system requirements and build backend tools to use
+  for creation of the package,
   the package metadata,
   the command-line interface scripts and entry points configuration
   (if applicable),
@@ -177,10 +178,12 @@ Three of those files that *must* be present contain the information necessary to
 The other three files are perhaps optional,
 but are present in most packages:
 
-* :ref:`PkgReadthedocsYamlFile` that provides configuration for building the docs to the https://readthedocs.org service
+* :ref:`PkgReadthedocsYamlFile` that provides configuration for building the docs to the `readthedocs service`_
 * :ref:`PkgGitignoreFile` that provides the list of intentionally untracked files that Git should ignore
-* :ref:`PkgPreCommitConfigYamlFile` that provides configuration for the `pre-commit`_ tool that is used to manage coding style and other aspects of repository QA
+* :ref:`PkgPreCommitConfigYamlFile` that provides configuration for the `pre-commit`_
+  tool that is used to manage coding style and other aspects of repository QA
 
+.. _readthedocs service: https://about.readthedocs.com/?ref=readthedocs.org
 .. _pre-commit: https://pre-commit.com/
 
 
@@ -371,7 +374,7 @@ line in the ``[project]`` section of the :ref:`PyprojectTomlFile`.
 :file:`.readthedocs.yaml` File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For packages that use https://readthedocs.org/ to render and host their documentation,
+For packages that use the `readthedocs service`_ to render and host their documentation,
 we include a :file:`.readthedocs.yaml` file in the top-level directory
 (the file name and location are stipulated by readthedocs).
 That file `declares the features of the environment`_ that we want readthedocs to use to build our docs,
@@ -776,7 +779,7 @@ used for code and docs QA tasks like:
 
 * static analysis of the code using `GitHub CodeQL`_ to detect possible security vulnerabilities
 
-  .. _GitHub CodeQL: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql
+  .. _GitHub CodeQL: https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql
 
 * run the package test suite with code coverage analysis (continuous integration)
   and pushing the coverage analysis report to `Codecov`/_

requirements.txt

@@ -4,77 +4,68 @@
 #   (moad-docs)$ python3 -m pip list --format=freeze >> requirements.txt
 
 alabaster==0.7.13
-attrs==22.2.0
+attrs==23.1.0
 Babel==2.12.1
-beautifulsoup4==4.12.0
+beautifulsoup4==4.12.2
 bleach==6.0.0
-brotlipy==0.7.0
 certifi==2023.7.22
 cffi==1.15.1
 cfgv==3.3.1
-charset-normalizer==2.1.1
-colorama==0.4.6
-cryptography==41.0.3
+charset-normalizer==3.2.0
 defusedxml==0.7.1
-distlib==0.3.6
-docutils==0.17.1
-entrypoints==0.4
-fastjsonschema==2.16.3
-filelock==3.10.7
-identify==2.5.22
+distlib==0.3.7
+docutils==0.18.1
+fastjsonschema==2.18.0
+filelock==3.12.3
+identify==2.5.28
 idna==3.4
 imagesize==1.4.1
-importlib-metadata==6.1.0
-importlib-resources==5.12.0
 Jinja2==3.1.2
-jsonschema==4.17.3
-jupyter_client==8.1.0
-jupyter_core==5.3.0
+jsonschema==4.19.0
+jsonschema-specifications==2023.7.1
+jupyter_client==8.3.1
+jupyter_core==5.3.1
 jupyterlab-pygments==0.2.2
-MarkupSafe==2.1.2
-mistune==2.0.5
-nbclient==0.7.2
-nbconvert==7.2.9
-nbformat==5.8.0
-nbsphinx==0.9.1
-nodeenv==1.7.0
-packaging==23.0
+MarkupSafe==2.1.3
+mistune==3.0.1
+nbclient==0.8.0
+nbconvert==7.8.0
+nbformat==5.9.2
+nbsphinx==0.9.3
+nodeenv==1.8.0
+packaging==23.1
 pandocfilters==1.5.0
-pip==23.0.1
-pkgutil_resolve_name==1.3.10
-platformdirs==3.2.0
-pre-commit==3.2.0
+pip==23.2.1
+platformdirs==3.10.0
+pre-commit==3.4.0
 pycparser==2.21
-Pygments==2.15.0
-pyOpenSSL==23.1.0
-pyrsistent==0.19.3
-PySocks==1.7.1
+Pygments==2.16.1
 python-dateutil==2.8.2
-pytz==2023.2
-PyYAML==6.0
-pyzmq==25.0.2
+PyYAML==6.0.1
+pyzmq==25.1.1
+referencing==0.30.2
 requests==2.31.0
-setuptools==67.6.0
+rpds-py==0.10.3
+setuptools==68.2.2
 six==1.16.0
 snowballstemmer==2.2.0
-soupsieve==2.3.2.post1
-Sphinx==5.3.0
-sphinx-notfound-page==0.8.3
-sphinx-rtd-theme==1.2.0
-sphinxcontrib-applehelp==1.0.4
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==2.0.1
+soupsieve==2.5
+Sphinx==7.2.5
+sphinx-notfound-page==1.0.0
+sphinx-rtd-theme==1.3.0
+sphinxcontrib-applehelp==1.0.7
+sphinxcontrib-devhelp==1.0.5
+sphinxcontrib-htmlhelp==2.0.4
 sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-qthelp==1.0.6
+sphinxcontrib-serializinghtml==1.1.9
 tinycss2==1.2.1
 tornado==6.3.3
 traitlets==5.9.0
-typing_extensions==4.5.0
+typing_extensions==4.7.1
 ukkonen==1.0.1
-urllib3==1.26.15
-virtualenv==20.21.0
+urllib3==2.0.4
+virtualenv==20.24.4
 webencodings==0.5.1
-wheel==0.40.0
-zipp==3.15.0
+wheel==0.41.2

sphinx_docs.rst

@@ -26,7 +26,7 @@ We use `Sphinx`_ for most documentation in the UBC-MOAD projects and repositorie
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _LaTeX: https://www.latex-project.org/
 .. _MathJax: https://www.mathjax.org/
-.. _readthedocs: https://readthedocs.org/
+.. _readthedocs: https://about.readthedocs.com/?ref=readthedocs.org
 
 `LaTeX`_ should be used for manuscripts of papers and theses,
 and for reports for which PDFs must be rendered,
@@ -50,7 +50,7 @@ or `SalishSeaCast/NEMO-Cmd`_).
 Most of our repositories are configured so that when changes that have been committed and  pushed to GitHub a signal is sent to `readthedocs.org`_ to automatically rebuild and render the docs at a ``readthedocs.io`` sub-domain.
 There is a very good chance that you are presently reading the result of that processing pipeline at https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html#documentation-with-sphinx.
 
-.. _readthedocs.org: https://readthedocs.org/
+.. _readthedocs.org: https://about.readthedocs.com/?ref=readthedocs.org
 
 Links to a repository's docs can generally be found in the :file:`README`.
 

zzz_archival_docs/hg_version_control.rst

@@ -32,7 +32,7 @@ Users experienced with other version control tools
 (e.g :command:`svn` or :command:`git`)
 can get up to speed with Mercurial by reading `Chapter 2`_.
 
-.. _beginner's guides: https://www.mercurial-scm.org/wiki/BeginnersGuides
+.. _beginner's guides: https://wiki.mercurial-scm.org/BeginnersGuides
 .. _Mercurial - The Definitive Guide: http://hgbook.red-bean.com/
 .. _1: http://hgbook.red-bean.com/read/how-did-we-get-here.html
 .. _2: http://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html
@@ -247,8 +247,8 @@ That reserves branching and merging for the relatively rare occasions when tempo
 
 The `rebase extension docs`_ have more information and diagrams of what's going on in this `common rebase use case`_.
 
-.. _rebase extension docs: https://www.mercurial-scm.org/wiki/RebaseExtension
-.. _common rebase use case: https://www.mercurial-scm.org/wiki/RebaseExtension#Scenario_A
+.. _rebase extension docs:  https://wiki.mercurial-scm.org/RebaseExtension
+.. _common rebase use case: https://wiki.mercurial-scm.org/RebaseExtension#Scenario_A
 
 
 Rebasing an Accidental Branch
@@ -262,7 +262,7 @@ providing a way of visualizing branches.
 :command:`hg rebase` can be used to move the changes on an accidental branch to the tip of the repo.
 See the `scenarios section`_ of the `rebase extension docs`_ for diagrams and rebase command options for moving branches around in various ways.
 
-.. _scenarios section: https://www.mercurial-scm.org/wiki/RebaseExtension#Scenarios
+.. _scenarios section: https://wiki.mercurial-scm.org/RebaseExtension#Scenarios
 
 
 Aborting a Merge