diff --git a/alliance-computing.rst b/alliance-computing.rst index 54b0de0..e6cd8dc 100644 --- a/alliance-computing.rst +++ b/alliance-computing.rst @@ -122,15 +122,15 @@ You should be able to follow these instructions to set up on any of the other Al On Mac or Linux your public key is stored in ``$HOME/.ssh/id_ed25519.pub`` and you can display it so that you can copy/paste it to CCDB with: - .. code-block:: bash + .. code-block:: console - cat $HOME/.ssh/id_ed25519.pub + $ cat $HOME/.ssh/id_ed25519.pub On Windows you can do that with: - .. code-block:: powershell + .. code-block:: console - type %USERPROFILE%/.ssh/id_ed25519.pub + PS> type %USERPROFILE%/.ssh/id_ed25519.pub Alternatively, you can open your :file:`id_ed25519.pub` in VS Code and copy it from there to the CCDB page. @@ -139,7 +139,7 @@ You should be able to follow these instructions to set up on any of the other Al Confirm that you can :command:`ssh` into ``nibi`` with - .. code-block:: bash + .. code-block:: console $ ssh nibi @@ -152,7 +152,7 @@ You should be able to follow these instructions to set up on any of the other Al To ensure that :envvar:`PROJECT` is set correctly every time you sign in to ``nibi``, use an editor to add the following line to your :file:`$HOME/.bash_profile` file: - .. code-block:: text + .. code-block:: bash export PROJECT=$HOME/projects/def-allen @@ -160,7 +160,7 @@ You should be able to follow these instructions to set up on any of the other Al then :command:`ssh` in again, and confirm that :envvar:`PROJECT` is set correctly with: - .. code-block:: bash + .. code-block:: console $ echo $PROJECT @@ -174,7 +174,7 @@ You should be able to follow these instructions to set up on any of the other Al #. Create a directory for yourself in :file:`$PROJECT/`: - .. code-block:: bash + .. code-block:: console $ mkdir $PROJECT/$USER @@ -182,7 +182,7 @@ You should be able to follow these instructions to set up on any of the other Al ``def-allen`` group have access, and permissions from the top-level directory are inherited downward in the tree: - .. code-block:: bash + .. code-block:: console $ chgrp def-allen $PROJECT/$USER $ chmod g+rwxs $PROJECT/$USER @@ -190,7 +190,7 @@ You should be able to follow these instructions to set up on any of the other Al Check the results of those operations with :command:`ls -al $PROJECT/$USER`. They should look like: - .. code-block:: text + .. code-block:: console $ ls -al $PROJECT/$USER total 90 @@ -203,7 +203,7 @@ You should be able to follow these instructions to set up on any of the other Al of the ``def-allen`` group have access, and permissions from the top-level directory are inherited downward in the tree: - .. code-block:: bash + .. code-block:: console $ chgrp def-allen $SCRATCH $ chmod g+rwxs $SCRATCH @@ -211,7 +211,7 @@ You should be able to follow these instructions to set up on any of the other Al Check the results of those operations with :command:`ls -al $SCRATCH`. They should look like: - .. code-block:: text + .. code-block:: console $ ls -al $SCRATCH total 3015 @@ -225,11 +225,11 @@ You should be able to follow these instructions to set up on any of the other Al #. Alliance clusters use the :command:`module load` command to load software components. On ``nibi`` the module loads that are required to build and run NEMO are: - .. code-block:: bash + .. code-block:: console - module load StdEnv/2023 - module load netcdf-fortran-mpi/4.6.1 - module load perl/5.36.1 + $ module load StdEnv/2023 + $ module load netcdf-fortran-mpi/4.6.1 + $ module load perl/5.36.1 You can manually load the modules each time you log in, or you can add the above lines to your :file:`$HOME/.bashrc` file so that they are diff --git a/analysis_repo.rst b/analysis_repo.rst index acb3e12..374e31d 100644 --- a/analysis_repo.rst +++ b/analysis_repo.rst @@ -91,14 +91,14 @@ Clone Your Analysis Repository #. Create a top level directory for MOAD work. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ mkdir -p /ocean/$USER/MOAD Or, if you want to set things up on your laptop do: - .. code-block:: bash + .. code-block:: console $ mkdir -p $HOME/MOAD @@ -115,14 +115,17 @@ Clone Your Analysis Repository "Quick setup — if you’ve done this kind of thing before". Below that there are 2 buttons that say :guilabel:`HTTPS` and :guilabel:`SSH`. Please ensure that the :guilabel:`SSH` button is enabled, - and copy the repository URI string of text beside it that looks like:: + and copy the repository URI string of text beside it that looks like: - git@github.com:SalishSeaCast/analysis-casey.git + .. code-block:: output + :class: no-copybutton + + git@github.com:SalishSeaCast/analysis-casey.git #. Use that repository URI string to clone your analysis repository from GitHub. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ cd /ocean/$USER/MOAD $ git clone git@github.com:SalishSeaCast/analysis-casey.git @@ -130,7 +133,7 @@ Clone Your Analysis Repository Or, for laptop setup do: - .. code-block:: bash + .. code-block:: console $ cd $HOME/MOAD $ git clone git@github.com:SalishSeaCast/analysis-casey.git @@ -158,7 +161,7 @@ Populate Your Analysis Repository .. _cookiecutter tool: https://cookiecutter.readthedocs.io/en/latest/ - .. code-block:: bash + .. code-block:: console $ conda create -n cookiecutter -c conda-forge python=3 cookiecutter @@ -167,26 +170,29 @@ Populate Your Analysis Repository and ask you if it is okay to proceed; hit ``y`` or ``Enter`` to go ahead. - After some more processing you should see the messages:: + After some more processing you should see the messages: + + .. code-block:: output + :class: no-copybutton - Preparing transaction: done - Verifying transaction: done - Executing transaction: done - # - # To activate this environment, use - # - # $ conda activate cookiecutter - # - # To deactivate an active environment, use - # - # $ conda deactivate + Preparing transaction: done + Verifying transaction: done + Executing transaction: done + # + # To activate this environment, use + # + # $ conda activate cookiecutter + # + # To deactivate an active environment, use + # + # $ conda deactivate #. Activate the ``cookiecutter`` environment, go to your :file:`MOAD/` directory, and populate your empty analysis repository clone with the following commands. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ conda activate cookiecutter (cookiecutter)$ cd /ocean/$USER/MOAD @@ -195,7 +201,7 @@ Populate Your Analysis Repository Or, for laptop setup do: - .. code-block:: bash + .. code-block:: console $ conda activate cookiecutter (cookiecutter)$ cd $HOME/MOAD @@ -215,7 +221,10 @@ Populate Your Analysis Repository The ``-f`` option lets the :command:`cookiecutter` tool write directories and files into an already existing directory. - :command:`cookiecutter` will ask you for 2 pieces of input:: + :command:`cookiecutter` will ask you for 2 pieces of input: + + .. code-block:: output + :class: no-copybutton researcher_name [Casey Lawrence]: Select github_org: @@ -230,7 +239,7 @@ Populate Your Analysis Repository #. Deactivate your ``cookiecutter`` environment with: - .. code-block:: bash + .. code-block:: console (cookiecutter)$ conda deactivate @@ -239,7 +248,7 @@ Populate Your Analysis Repository and push them to GitHub. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ cd /ocean/$USER/MOAD/analysis-casey $ git add .gitignore LICENSE README.rst notebooks/ @@ -249,7 +258,7 @@ Populate Your Analysis Repository Or, for laptop setup do: - .. code-block:: bash + .. code-block:: console $ cd $HOME/MOAD/analysis-casey $ git add .gitignore LICENSE README.rst notebooks/ @@ -275,7 +284,7 @@ and the names of the Python packages to install in the environment. and use :command:`conda` to create the environment. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ cd /ocean/$USER/MOAD/analysis-casey/notebooks/ $ conda env create -f environment.yaml @@ -283,7 +292,7 @@ and the names of the Python packages to install in the environment. Or, for laptop setup do: - .. code-block:: bash + .. code-block:: console $ cd $HOME/MOAD/analysis-casey/notebooks/ $ conda env create -f environment.yaml @@ -294,19 +303,22 @@ and the names of the Python packages to install in the environment. and ask you if it is okay to proceed; hit ``y`` or ``Enter`` to go ahead. - After some more processing you should see messages like:: + After some more processing you should see messages like: + + .. code-block:: output + :class: no-copybutton - Preparing transaction: done - Verifying transaction: done - Executing transaction: done - # - # To activate this environment, use - # - # $ conda activate analysis-casey - # - # To deactivate an active environment, use - # - # $ conda deactivate + Preparing transaction: done + Verifying transaction: done + Executing transaction: done + # + # To activate this environment, use + # + # $ conda activate analysis-casey + # + # To deactivate an active environment, use + # + # $ conda deactivate Use the :command:`conda activate` command to activate your analysis environment so that you can run :ref:`MOAD-Jupyter`. @@ -330,7 +342,7 @@ The `documentation for the package`_ contains documentation for most of its func #. Clone the `SalishSeaTools`_ repository beside your analysis repository. On a Waterhole workstation do: - .. code-block:: bash + .. code-block:: console $ cd /ocean/$USER/MOAD/ $ git clone git@github.com:SalishSeaCast/tools.git @@ -338,7 +350,7 @@ The `documentation for the package`_ contains documentation for most of its func Or, for laptop setup do: - .. code-block:: bash + .. code-block:: console $ cd $HOME/MOAD/ $ git clone git@github.com:SalishSeaCast/tools.git @@ -347,10 +359,10 @@ The `documentation for the package`_ contains documentation for most of its func (if you haven't already done so) and install the `SalishSeaTools`_ package in it: - .. code-block:: bash + .. code-block:: console $ conda activate analysis-casey - (analysis-casey)$ python3 -m pip install --editable tools/SalishSeaTools + (analysis-casey)$ python -m pip install --editable tools/SalishSeaTools The ``--editable`` option in the :command:`pip install` command installs the packages in a way that it can be updated when new features are pushed to GitHub by simply doing a diff --git a/ariane.rst b/ariane.rst index 1ed4035..0177077 100644 --- a/ariane.rst +++ b/ariane.rst @@ -39,10 +39,10 @@ The MOAD group maintains our own Git repository on GitHub of the Ariane code bas .. _Ariane website: http://ariane.lagrangian.free.fr/download.php .. _GitHub: https://github.com/UBC-MOAD/ariane-2.3.0_03 -.. code-block:: bash +.. code-block:: console - cd /ocean/$USER/$PROJECT/ - git clone git@github.com:UBC-MOAD/ariane-2.3.0_03.git + $ cd /ocean/$USER/$PROJECT/ + $ git clone git@github.com:UBC-MOAD/ariane-2.3.0_03.git Installing on ``salish`` @@ -50,29 +50,29 @@ Installing on ``salish`` Configure the installation by going to the folder of your clone of the MOAD Ariane repo: -.. code-block:: bash +.. code-block:: console - cd /ocean/$USER/$PROJECT/ariane-2.3.0_03 - ./configure --prefix=$PWD + $ cd /ocean/$USER/$PROJECT/ariane-2.3.0_03 + $ ./configure --prefix=$PWD The ``prefix`` argument overwrites the default install directory into a customized directory. Make and install Ariane (you will need to do this every time you make changes to the code): -.. code-block:: bash +.. code-block:: console - cd /ocean/$USER/$PROJECT/ariane-2.3.0_03 - make - make check - make install + $ cd /ocean/$USER/$PROJECT/ariane-2.3.0_03 + $ make + $ make check + $ make install Add the path for the Ariane executable to your ``PATH`` environment variable: -.. code-block:: bash +.. code-block:: console export PATH=$PWD/bin:$PATH -Now you can run Ariane from any directory by typing ``ariane``. +Now you can run Ariane from any directory by typing :command:`ariane`. Testing Ariane installation @@ -81,10 +81,10 @@ Testing Ariane installation To test that you have everything set up correctly, run one of the Ariane examples. For instance, try: -.. code-block:: bash +.. code-block:: console - cd /ocean/$USER/$PROJECT/ariane-2.3.0_03/examples/qualitative - ariane + $ cd /ocean/$USER/$PROJECT/ariane-2.3.0_03/examples/qualitative + $ ariane You should notice several new files, such as :file:`results/ariane_trajectories_qualitative.nc` and :file:`validation/traj.txt`. These files contain the trajectory information. @@ -100,7 +100,7 @@ Qualitative Mode This mode can be used to get the exact path of a set number of particles. -:file:`intitial_positions.txt` +:file:`initial_positions.txt` ------------------------------ The :file:`initial_positions.txt` file specifies the initial positions and release times of the particles that you are tracking. This file consists of 5 columns and a row for each particle that you are running. @@ -359,15 +359,15 @@ Ariane provides a couple of useful tools for defining the sections. * :kbd:`mkseg0`: This program reads your land-ocean mask and writes it as a text file. Run this program in the same directory as your namelist. You may need to add the ariane executables to your path. -.. code-block:: bash +.. code-block:: console - mkseg0 + $ mkseg0 * :file:`segrid`: After you run :kbd:`mkseg0`, you should see a new file called :file:`segrid`. Edit this file with -.. code-block:: bash +.. code-block:: console - nedit segrid + $ nedit segrid * If you turn off text wrapping, you might see something like this: @@ -382,7 +382,10 @@ Land points are :kbd:`#` and ocean points are :kbd:`-`. * Run :kbd:`mkseg` * This will print out whether you succeeded or not and let you know the extent of the sections you defined. If something went wrong in editing :file:`segrid` the message will let you know how, this usually entails accidentally deleting a land point, not closing your boundaries, or forgetting to place the :kbd:`@` symbol somewhere! -* Once you have that without errors, section definitions will be copied automatically into a file called :file:`sections.txt`. The section definitions should look something like this:: +* Once you have that without errors, section definitions will be copied automatically into a file called :file:`sections.txt`. + The section definitions should look something like this: + + .. code-block:: text 1 250 313 -409 -409 1 40 "1section" 2 264 312 386 386 1 40 "2section" @@ -394,50 +397,53 @@ You can rename :kbd:`"1section"` and :kbd:`"2section"` to something more intuiti Analyzing quantitative output ----------------------------- -A new file called :file:`stats.txt` contains statistics about the initial and final particles through each section and the transport calculations. It might look something like this:: - - total transport (in m3/s): 230033.88767527405 ( x lmt = 5520813.3042065771 ) - max_transport (in m3/s) : 1000000000.0000000 - # particles : 20380 - - initial state # 20380 - stats. for: x y z a - min: -123.457 48.946 0.500 0.000 - max: -123.134 49.063 226.275 0.000 - mean: -123.347 48.986 74.893 0.000 - std. dev.: 0.062 0.022 61.722 0.000 - - meanders 166079.1572 0 - 1section .0000 1 - 2section 63952.7799 2 - Surface .0000 3 - total 230033.8877 - except mnds 63954.7305 - lost 1.9506 - - final state meanders # 11094 - stats. ini: x y z a - min: -123.457 48.946 0.500 0.006 - max: -123.134 49.063 226.275 16.858 - mean: -123.343 48.987 91.665 0.606 - std. dev.: 0.055 0.020 61.438 1.010 - stats. fin: x y z a - min: -123.458 48.945 0.019 0.006 - max: -123.132 49.064 238.621 16.858 - mean: -123.329 48.992 91.483 0.606 - std. dev.: 0.052 0.019 62.670 1.010 - - final state 2section # 9285 - stats. ini: x y z a - min: -123.457 48.946 0.500 0.191 - max: -123.134 49.063 226.275 16.074 - mean: -123.357 48.982 31.337 1.715 - std. dev.: 0.075 0.028 35.675 1.639 - stats. fin: x y z a - min: -123.317 48.883 0.058 0.191 - max: -123.079 48.970 151.722 16.074 - mean: -123.192 48.929 25.504 1.715 - std. dev.: 0.068 0.025 25.477 1.639 +A new file called :file:`stats.txt` contains statistics about the initial and final particles through each section and the transport calculations. +It might look something like this: + +.. code-block:: text + + total transport (in m3/s): 230033.88767527405 ( x lmt = 5520813.3042065771 ) + max_transport (in m3/s) : 1000000000.0000000 + # particles : 20380 + + initial state # 20380 + stats. for: x y z a + min: -123.457 48.946 0.500 0.000 + max: -123.134 49.063 226.275 0.000 + mean: -123.347 48.986 74.893 0.000 + std. dev.: 0.062 0.022 61.722 0.000 + + meanders 166079.1572 0 + 1section .0000 1 + 2section 63952.7799 2 + Surface .0000 3 + total 230033.8877 + except mnds 63954.7305 + lost 1.9506 + + final state meanders # 11094 + stats. ini: x y z a + min: -123.457 48.946 0.500 0.006 + max: -123.134 49.063 226.275 16.858 + mean: -123.343 48.987 91.665 0.606 + std. dev.: 0.055 0.020 61.438 1.010 + stats. fin: x y z a + min: -123.458 48.945 0.019 0.006 + max: -123.132 49.064 238.621 16.858 + mean: -123.329 48.992 91.483 0.606 + std. dev.: 0.052 0.019 62.670 1.010 + + final state 2section # 9285 + stats. ini: x y z a + min: -123.457 48.946 0.500 0.191 + max: -123.134 49.063 226.275 16.074 + mean: -123.357 48.982 31.337 1.715 + std. dev.: 0.075 0.028 35.675 1.639 + stats. fin: x y z a + min: -123.317 48.883 0.058 0.191 + max: -123.079 48.970 151.722 16.074 + mean: -123.192 48.929 25.504 1.715 + std. dev.: 0.068 0.025 25.477 1.639 * :kbd:`lost` are the particles not intercepted by any section. * :kbd:`meanders` are the particles that go back out the source section (section 1). Note that this is actually a bad translation from the original french Ariane was writen in. It would be more accurate to think of these particles as :kbd:`loop`. @@ -752,15 +758,15 @@ Calling the Run Ariane Script Calling this script takes a bit more information than most, in your command line type the following: -.. code-block:: bash +.. code-block:: console - python3 path_to_RunAriane.py startday number_of_loops days_with_particles_seeding total_days_in_run forward_or_backward target_subdirectory_name + $ python3 path_to_RunAriane.py startday number_of_loops days_with_particles_seeding total_days_in_run forward_or_backward target_subdirectory_name for example, the following was typed into the command line for 30 days of seeding, 30 days of run after seeding is completed, foward run, starting January 1st 2018: -.. code-block:: bash +.. code-block:: console - python3 ./RunAriane_manydays.py 2018-01-01 1 30 30 forward 201905_1hr + $ python3 ./RunAriane_manydays.py 2018-01-01 1 30 30 forward 201905_1hr Frequency Sensitivity Sample diff --git a/bash_config.rst b/bash_config.rst index 1e9541f..6a9e736 100644 --- a/bash_config.rst +++ b/bash_config.rst @@ -25,14 +25,17 @@ they mean typing commands into a terminal session. You can find out what shell you are using in most terminal sessions with the command: -.. code-block:: bash +.. code-block:: console - echo $SHELL + $ echo $SHELL If the shell you are using is :command:`bash`, -the output of that command will most likely be:: +the output of that command will most likely be: + +.. code-block:: output + :class: no-copybutton - /bin/bash + /bin/bash In order to make :command:`bash` work well for us on the Waterhole workstations and other MOAD computers, we have to create or edit two configuration files in our home directory: @@ -71,7 +74,7 @@ or when you start up a terminal session. Use the :command:`nano` text editor to open the :file:`.bash_profile` file: -.. code-block:: bash +.. code-block:: console $ nano .bash_profile @@ -122,7 +125,7 @@ The other important :command:`bash` configuration file is :file:`.bashrc`. Use the :command:`nano` text editor to open the :command:`.bashrc` file: -.. code-block:: bash +.. code-block:: console $ nano .bashrc @@ -181,7 +184,7 @@ and exit :command:`nano`. You will have to leave the shell by typing the command: -.. code-block:: bash +.. code-block:: console $ exit diff --git a/conda_pkg_env_mgr.rst b/conda_pkg_env_mgr.rst index 07b1329..9834132 100644 --- a/conda_pkg_env_mgr.rst +++ b/conda_pkg_env_mgr.rst @@ -52,7 +52,7 @@ so you might as well get started that way by using :program:`wget` to download t On Linux, macOS and Windows Subsystem for Linux (WSL) use: -.. code-block:: bash +.. code-block:: console $ wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" @@ -62,7 +62,7 @@ In short: #. Run the installer script via :program:`bash`: - .. code-block:: bash + .. code-block:: console $ bash Miniforge3-$(uname)-$(uname -m).sh @@ -77,7 +77,8 @@ In short: A list of installed packages appears if it has been installed correctly; it looks something like: - .. code-block:: text + .. code-block:: output + :class: no-copybutton # packages in environment at /home/dlatorne/miniforge3: # @@ -162,7 +163,7 @@ and on the Waterhole workstation that you use The :command:`conda config` command is how you interact with the :file:`$HOME/.condarc` file. Start by telling :program:`conda` where you want to store your environments: -.. code-block:: bash +.. code-block:: console $ conda config --prepend envs_dirs $HOME/conda_envs/ $ mkdir $HOME/conda_envs/ @@ -179,7 +180,7 @@ If you want to see all of the :program:`conda` configuration settings and the supplements from your :file:`$HOME/.condarc` file, you can use: -.. code-block:: bash +.. code-block:: console $ conda config --show diff --git a/conf.py b/conf.py index 418f63d..4a62fde 100644 --- a/conf.py +++ b/conf.py @@ -36,6 +36,7 @@ 'nbsphinx', "notfound.extension", 'sphinx.ext.intersphinx', + "sphinx_copybutton", ] intersphinx_mapping = { @@ -103,6 +104,15 @@ pygments_style = 'sphinx' +# -- Options for sphinx_copybutton extension ------------------------------ + +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: |PS> " +copybutton_prompt_is_regexp = True +copybutton_line_continuation_character = "\\" +# Add a `no-copybutton` class that can be used to suppress the copy button +copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre" + + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/contributing.rst b/contributing.rst index 46f35f9..9b311b0 100644 --- a/contributing.rst +++ b/contributing.rst @@ -64,7 +64,7 @@ Clone the MOAD documentation `repository`_ from GitHub with: .. _repository: https://github.com/UBC-MOAD/docs -.. code-block:: bash +.. code-block:: console $ git clone git@github.com:UBC-MOAD/docs.git @@ -126,14 +126,15 @@ To do a clean build of the documentation use: .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _Sphinx: https://www.sphinx-doc.org/en/master/ -.. code-block:: bash +.. code-block:: console - cd docs/ - pixi run docs + $ cd docs/ + $ pixi run docs The output looks something like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton ✨ Pixi task (docs): make clean html Removing everything under '_build'... @@ -180,9 +181,9 @@ The HTML rendering of the docs ends up in :file:`docs/_build/html/`. You can open the :file:`index.html` file in that directory tree in your browser to preview the results of the build. To preview in Firefox from the command-line you can do: -.. code-block:: bash +.. code-block:: console - firefox _build/html/index.html + $ firefox _build/html/index.html If you have write access to the `repository`_ on GitHub, whenever you push changes to GitHub the documentation is automatically re-built and rendered at @@ -201,225 +202,226 @@ Link Checking the Documentation Sphinx also provides a link checker utility which can be run to find broken or redirected links in the docs. Run the link checker with: -.. code-block:: bash +.. code-block:: console - cd docs/ - pixi run linkcheck + $ cd docs/ + $ pixi run linkcheck The output looks something like: -.. code-block:: text - - ✨ Pixi task (linkcheck): make clean linkcheck - Removing everything under '_build'... - Running Sphinx v8.1.3 - loading translations [en]... done - making output directory... done - loading intersphinx inventory 'moadtools' from https://ubc-moad-tools.readthedocs.io/en/latest/objects.inv ... - loading intersphinx inventory 'nemocmd' from https://nemo-cmd.readthedocs.io/en/latest/objects.inv ... - loading intersphinx inventory 'salishseacmd' from https://salishseacmd.readthedocs.io/en/latest/objects.inv ... - loading intersphinx inventory 'salishseadocs' from https://salishsea-meopar-docs.readthedocs.io/en/latest/objects.inv ... - building [mo]: targets for 0 po files that are out of date - writing output... - building [linkcheck]: targets for 24 source files that are out of date - updating environment: [new config] 24 added, 0 changed, 0 removed - reading sources... [100%] zzz_archival_docs/index - looking for now-outdated files... none found - pickling environment... done - checking consistency... done - preparing documents... done - copying assets... - copying assets: done - writing output... [100%] zzz_archival_docs/index - - ( ariane: line 37) -ignored- https://github.com/UBC-MOAD/ariane-2.3.0_03 - ( ssh_access: line 26) -ignored- https://www.baeldung.com/cs/ssh-intro - ( ssh_access: line 556) -ignored- https://linux.die.net/man/1/scp - ( xios-2: line 41) -ignored- https://github.com/SalishSeaCast/XIOS-2 - ( xios-2: line 210) -ignored- https://github.com/SalishSeaCast/NEMO-3.6-code - ( ariane: line 25) ok http://ariane.lagrangian.free.fr/ariane_tutorial_2.x.x_sep08.pdf - ( ariane: line 15) ok http://ariane.lagrangian.free.fr/whatsariane.html - ( ariane: line 24) ok http://ariane.lagrangian.free.fr/ariane_namelist_2.x.x_oct08.pdf - ( ariane: line 37) ok http://ariane.lagrangian.free.fr/download.php - ( ariane: line 23) ok http://ariane.lagrangian.free.fr/ariane_install_2.x.x_sep08.pdf - (python_packaging/pkg_structure: line 181) ok https://about.readthedocs.com/?ref=readthedocs.org - (python_packaging/pkg_structure: line 38) ok https://blog.ionelmc.ro/2014/05/25/python-packaging/ - (zzz_archival_docs/hg_version_control: line 41) ok https://bitbucket.org/ - ( contributing: line 21) ok https://app.readthedocs.org/projects/ubc-moad-docs/badge/?version=latest - ( globus: line 27) ok https://app.globus.org/file-manager - (git_version_control: line 60) ok https://brew.sh/ - (python_packaging/pkg_structure: line 39) ok https://bskinn.github.io/My-How-Why-Pyproject-Src/ - (python_packaging/pkg_structure: line 483) ok https://calver.org/ - (python_packaging/pkg_structure: line 296) ok https://click.palletsprojects.com/en/latest/ - (alliance-computing: line 85) redirect https://ccdb.alliancecan.ca/me/access_systems - with Found to https://ccdb.alliancecan.ca/security/login - ( contributing: line 46) ok https://app.readthedocs.org/projects/ubc-moad-docs/builds/ - ( xios-2: line 405) ok https://cfconventions.org/Data/cf-standard-names/29/build/cf-standard-name-table.html - (alliance-computing: line 55) ok https://ccdb.alliancecan.ca/account_application - ( analysis_repo: line 156) ok https://cookiecutter.readthedocs.io/en/latest/ - (python_packaging/pkg_structure: line 164) ok https://coverage.readthedocs.io/en/latest/ - (github_notebooks_readme: line 7) ok https://commonmark.org/ - ( contributing: line 13) ok https://creativecommons.org/licenses/by/4.0/ - (python_packaging/pkg_structure: line 745) ok https://doc.pytest.org/en/latest/explanation/goodpractices.html#tests-outside-application-code - (conda_pkg_env_mgr: line 39) ok https://conda-forge.org/ - ( vscode: line 15) ok https://code.visualstudio.com/ - ( jupyter: line 442) ok https://docs.alliancecan.ca/wiki/Anaconda/en - (alliance-computing: line 63) ok https://docs.alliancecan.ca/wiki/Apply_for_a_CCDB_account - (alliance-computing: line 120) ok https://docs.alliancecan.ca/wiki/SSH_Keys#Using_CCDB - (alliance-computing: line 72) ok https://docs.alliancecan.ca/wiki/Multifactor_authentication - (alliance-computing: line 69) ok https://docs.alliancecan.ca/wiki/Getting_started - ( jupyter: line 482) ok https://docs.alliancecan.ca/wiki/Python#Creating_and_using_a_virtual_environment - (python_packaging/pkg_structure: line 60) ok https://docs.conda.io/projects/conda/en/latest/ - (python_packaging/pkg_structure: line 773) ok https://docs.github.com/en/actions - ( contributing: line 77) ok https://docs.github.com/en/authentication/connecting-to-github-with-ssh - (conda_pkg_env_mgr: line 186) ok https://docs.conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html - (python_packaging/pkg_structure: line 778) ok https://docs.github.com/en/code-security/concepts/code-scanning/codeql/about-code-scanning-with-codeql - (conda_pkg_env_mgr: line 15) ok https://docs.conda.io/en/latest/ - ( ssh_access: line 506) ok https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account - (git_version_control: line 22) ok https://docs.github.com/en/get-started - (oceanparcels/index: line 23) ok https://docs.oceanparcels.org/en/latest/reference/predefined_kernels.html - ( contributing: line 13) ok https://docs.python.org/3/ - (python_packaging/pkg_structure: line 376) ok https://docs.readthedocs.com/platform/stable/config-file/v2.html - ( bash_config: line 43) ok https://douglatornell.github.io/2013-09-26-ubc/lessons/ref/shell.html - ( xios-2: line 160) ok https://en.wikipedia.org/wiki/XML - (python_packaging/pkg_structure: line 761) ok https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-security-updates - (python_packaging/pkg_structure: line 279) ok https://docs.openstack.org/cliff/latest/ - ( vscode: line 157) ok https://fortls.fortran-lang.org/index.html - ( contributing: line 434) ok https://git-scm.com/ - (git_version_control: line 22) ok https://git-scm.com/book/en/v2 - (git_version_control: line 22) ok https://git-scm.com/doc - (git_version_control: line 127) ok https://git-scm.com/docs/git-config - (git_version_control: line 56) ok https://git-scm.com/downloads - (git_version_control: line 213) ok https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository - (git_version_control: line 151) ok https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Setup-and-Config#ch_core_editor - ( getting_started: line 55) ok https://github.com/ - ( xios-2: line 297) ok https://forge.ipsl.fr/ioserver/raw-attachment/wiki/WikiStart/XIOS_user_guide.pdf - ( vcs_repos: line 19) ok https://github.com/MIDOSS/ - ( xios-2: line 15) ok https://forge.ipsl.fr/ioserver/wiki - ( sphinx_docs: line 36) ok https://github.com/MIDOSS/docs - (oceanparcels/index: line 21) ok https://github.com/Parcels-code/Parcels/discussions - ( vcs_repos: line 18) ok https://github.com/SalishSeaCast/ - ( analysis_repo: line 62) ok https://github.com/SalishSeaCast - ( xios-2: line 417) ok https://github.com/SalishSeaCast/SS-run-sets/tree/main/v201702 - ( xios-2: line 216) ok https://github.com/SalishSeaCast/SS-run-sets - ( xios-2: line 41) ok https://github.com/SalishSeaCast/XIOS-ARCH - (python_packaging/pkg_structure: line 24) ok https://github.com/SalishSeaCast/NEMO-Cmd - ( analysis_repo: line 33) ok https://github.com/SalishSeaCast/analysis-susan - (github_notebooks_readme: line 7) ok https://github.com/SalishSeaCast/analysis-ben/tree/master/notebooks - ( sphinx_docs: line 36) ok https://github.com/SalishSeaCast/docs - ( getting_started: line 55) ok https://github.com/UBC-MOAD - ( vcs_repos: line 17) ok https://github.com/UBC-MOAD/ - ( analysis_repo: line 316) ok https://github.com/SalishSeaCast/tools - ( sphinx_docs: line 79) ok https://github.com/UBC-MOAD/PythonNotes/blob/main/sphinx-docs/SphinxDocsTutorial.ipynb - (conda_pkg_env_mgr: line 31) ok https://github.com/UBC-MOAD/PythonNotes/blob/main/pkgs-envs/PythonPkgsEnvsSlides-2023.ipynb - ( contributing: line 13) ok https://github.com/UBC-MOAD/docs - (python_packaging/pkg_structure: line 296) ok https://github.com/UBC-MOAD/Reshapr - ( analysis_repo: line 51) ok https://github.com/UBC-MOAD/cookiecutter-analysis-repo - ( contributing: line 24) ok https://github.com/UBC-MOAD/docs/workflows/sphinx-linkcheck/badge.svg - ( contributing: line 460) ok https://github.com/UBC-MOAD/docs/blob/main/CONTRIBUTORS.rst - ( contributing: line 13) ok https://github.com/UBC-MOAD/docs/issues - (python_packaging/pkg_structure: line 799) ok https://github.com/UBC-MOAD/gha-workflows - ( sphinx_docs: line 36) ok https://github.com/UBC-MOAD/moad_tools - (python_packaging/pkg_structure: line 419) ok https://github.com/github/gitignore - (conda_pkg_env_mgr: line 39) ok https://github.com/conda-forge/miniforge - (python_packaging/pkg_structure: line 35) ok https://hatch.pypa.io/latest/ - (python_packaging/pkg_structure: line 202) ok https://hatch.pypa.io/latest/config/metadata/ - ( contributing: line 13) ok https://github.com/UBC-MOAD/docs/actions?query=workflow:sphinx-linkcheck - (git_version_control: line 215) ok https://github.com/github/gitignore/blob/main/Python.gitignore - ( jupyter: line 511) ok https://github.com/h5netcdf/h5netcdf - ( contributing: line 15) ok https://img.shields.io/badge/license-CC--BY-lightgrey.svg - ( contributing: line 30) ok https://img.shields.io/badge/python-3.14-blue.svg - ( contributing: line 18) ok https://img.shields.io/badge/version%20control-git-blue.svg?logo=github - ( contributing: line 89) ok https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json - (python_packaging/pkg_structure: line 37) ok https://hynek.me/articles/testing-packaging/ - ( jupyter: line 24) ok https://jupyter-notebook.readthedocs.io/en/stable/ - (github_notebooks_readme: line 12) ok https://jupyter.org/ - ( contributing: line 27) ok https://img.shields.io/github/issues/UBC-MOAD/docs?logo=github - ( ssh_access: line 71) ok https://learn.microsoft.com/en-ca/windows-server/administration/openssh/openssh_install_firstuse - ( vscode: line 123) ok https://marketplace.visualstudio.com/items?itemName=Digoro.Clipboard - (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/read/how-did-we-get-here.html - (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html - (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/ - ( vscode: line 129) ok https://marketplace.visualstudio.com/items?itemName=fortran-lang.linter-gfortran - ( vscode: line 111) ok https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens - ( vscode: line 136) ok https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv - ( vscode: line 96) ok https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter-renderers - ( vscode: line 148) ok https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf - ( vscode: line 42) ok https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh - ( vscode: line 117) ok https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker - ( vscode: line 142) ok https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst - ( jupyter: line 120) ok https://marketplace.visualstudio.com/items?itemName=ms-python.python - (github_notebooks_readme: line 12) ok https://nbviewer.org/ - ( ariane: line 560) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/Ariane_Tracers.ipynb - (oceanparcels/index: line 24) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/OceanParcelsRecipes.ipynb - ( xios-2: line 26) ok https://nemo-cmd.readthedocs.io/en/latest/index.html#nemo-commandprocessor - ( xios-2: line 236) ok https://nemo-cmd.readthedocs.io/en/latest/run_description_file/3.6_yaml_file.html#output-section - ( python: line 20) ok https://numpy.org/ - ( ariane: line 195) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/ParticleTracking.ipynb - (python_packaging/pkg_structure: line 36) ok https://packaging.python.org/en/latest/ - (python_packaging/pkg_structure: line 67) ok https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-to-the-user-site - (oceanparcels/index: line 22) ok https://os.copernicus.org/articles/17/1067/2021/ - ( python: line 20) ok https://pandas.pydata.org/ - (oceanparcels/index: line 19) ok https://parcels-code.org/ - (oceanparcels/index: line 13) ok https://parcels-code.org/index.html - (python_packaging/pkg_structure: line 483) ok https://peps.python.org/pep-0440/ - (python_packaging/pkg_structure: line 53) ok https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs - ( contributing: line 87) ok https://pixi.prefix.dev/latest/ - (conda_pkg_env_mgr: line 30) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/pkgs-envs/PythonPkgsEnvsSlides-2023.ipynb - ( contributing: line 93) ok https://pixi.prefix.dev/latest/installation/ - ( jupyter: line 499) ok https://pypi.org/ - ( python: line 51) ok https://realpython.com/ - ( sphinx_docs: line 183) ok https://rhodesmill.org/brandon/2012/one-sentence-per-line/ - (python_packaging/pkg_structure: line 183) ok https://pre-commit.com/ - (alliance-computing: line 248) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#compilenemo-3-6-nibi - (alliance-computing: line 242) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#installcommandprocessorpackages - (alliance-computing: line 238) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#createworkspaceandclonerepositories - ( analysis_repo: line 320) ok https://salishsea-meopar-tools.readthedocs.io/en/latest/SalishSeaTools/index.html - ( analysis_repo: line 320) ok https://salishsea-meopar-tools.readthedocs.io/en/latest/visualisation/visualization_workflows_xarray.html - (alliance-computing: line 242) ok https://salishseacmd.readthedocs.io/en/latest/index.html#salishseacmdprocessor - ( xios-2: line 236) ok https://salishseacmd.readthedocs.io/en/latest/run_description_file/3.6_yaml_file.html#output-section - (oceanparcels/index: line 20) ok https://salishseacast.slack.com/?redir=%2Farchives%2FC02ETTPHFPX - (git_version_control: line 151) ok https://salishseacast.slack.com/?redir=%2Farchives%2FCFR6VU70S - ( sphinx_docs: line 78) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/sphinx-docs/SphinxDocsTutorial.ipynb - (python_packaging/pkg_structure: line 40) ok https://snarky.ca/clarifying-pep-518/ - ( bash_config: line 43) ok https://software-carpentry.org/ - (zzz_archival_docs/hg_version_control: line 48) ok https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/ - (python_packaging/pkg_structure: line 826) ok https://tox.wiki/en/latest/ - ( contributing: line 13) ok https://ubc-moad-docs.readthedocs.io/en/latest/ - ( sphinx_docs: line 50) ok https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html#documentation-with-sphinx - ( sphinx_docs: line 88) ok https://ubc-moad-tools.readthedocs.io/en/latest/pkg_development.html#moad-toolspackageddevelopment - (zzz_archival_docs/hg_version_control: line 75) ok https://tortoisehg.bitbucket.io/ - (zzz_archival_docs/hg_version_control: line 27) ok https://wiki.mercurial-scm.org/BeginnersGuides - (zzz_archival_docs/hg_version_control: line 248) ok https://wiki.mercurial-scm.org/RebaseExtension#Scenario_A - (zzz_archival_docs/hg_version_control: line 248) ok https://wiki.mercurial-scm.org/RebaseExtension - (zzz_archival_docs/hg_version_control: line 262) ok https://wiki.mercurial-scm.org/RebaseExtension#Scenarios - (conda_pkg_env_mgr: line 15) ok https://www.anaconda.com/download - ( ariane: line 787) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/Ariane_TimeRes.ipynb - (python_packaging/pkg_structure: line 355) ok https://www.apache.org/licenses/ - ( CONTRIBUTORS: line 7) ok https://www.eoas.ubc.ca/~sallen/ - ( ssh_access: line 31) ok https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server - ( globus: line 15) ok https://www.globus.org/data-transfer - ( sphinx_docs: line 19) ok https://www.mathjax.org/ - (alliance-computing: line 15) ok https://www.alliancecan.ca/en - ( python: line 15) ok https://www.python.org/ - (zzz_archival_docs/hg_version_control: line 63) ok https://www.mercurial-scm.org/install - (zzz_archival_docs/hg_version_control: line 21) ok https://www.mercurial-scm.org/ - (zzz_archival_docs/hg_version_control: line 75) ok https://www.sourcetreeapp.com/ - ( contributing: line 121) ok https://www.sphinx-doc.org/en/master/ - ( sphinx_docs: line 19) ok https://www.latex-project.org/ - (python_packaging/pkg_structure: line 702) ok https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html - (python_packaging/pkg_structure: line 787) ok https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder - (python_packaging/pkg_structure: line 702) ok https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports - ( sphinx_docs: line 260) ok https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx - (zzz_archival_docs/hg_version_control: line 208) ok https://www.selenic.com/mercurial/hgignore.5.html - (zzz_archival_docs/hg_version_control: line 171) ok https://www.selenic.com/mercurial/hgrc.5.html - ( contributing: line 121) ok https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - ( sphinx_docs: line 57) ok https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html - ( python: line 20) ok https://www.tomasbeuzen.com/python-programming-for-data-science/README.html - ( python: line 20) ok https://www.tomasbeuzen.com/ - ( xios-2: line 199) ok https://www.xmlvalidation.com/ - build succeeded. - - Look for any errors in the above output or in _build/linkcheck/output.txt +.. code-block:: output + :class: no-copybutton + + ✨ Pixi task (linkcheck): make clean linkcheck + Removing everything under '_build'... + Running Sphinx v8.1.3 + loading translations [en]... done + making output directory... done + loading intersphinx inventory 'moadtools' from https://ubc-moad-tools.readthedocs.io/en/latest/objects.inv ... + loading intersphinx inventory 'nemocmd' from https://nemo-cmd.readthedocs.io/en/latest/objects.inv ... + loading intersphinx inventory 'salishseacmd' from https://salishseacmd.readthedocs.io/en/latest/objects.inv ... + loading intersphinx inventory 'salishseadocs' from https://salishsea-meopar-docs.readthedocs.io/en/latest/objects.inv ... + building [mo]: targets for 0 po files that are out of date + writing output... + building [linkcheck]: targets for 24 source files that are out of date + updating environment: [new config] 24 added, 0 changed, 0 removed + reading sources... [100%] zzz_archival_docs/index + looking for now-outdated files... none found + pickling environment... done + checking consistency... done + preparing documents... done + copying assets... + copying assets: done + writing output... [100%] zzz_archival_docs/index + + ( ariane: line 37) -ignored- https://github.com/UBC-MOAD/ariane-2.3.0_03 + ( ssh_access: line 26) -ignored- https://www.baeldung.com/cs/ssh-intro + ( ssh_access: line 556) -ignored- https://linux.die.net/man/1/scp + ( xios-2: line 41) -ignored- https://github.com/SalishSeaCast/XIOS-2 + ( xios-2: line 210) -ignored- https://github.com/SalishSeaCast/NEMO-3.6-code + ( ariane: line 25) ok http://ariane.lagrangian.free.fr/ariane_tutorial_2.x.x_sep08.pdf + ( ariane: line 15) ok http://ariane.lagrangian.free.fr/whatsariane.html + ( ariane: line 24) ok http://ariane.lagrangian.free.fr/ariane_namelist_2.x.x_oct08.pdf + ( ariane: line 37) ok http://ariane.lagrangian.free.fr/download.php + ( ariane: line 23) ok http://ariane.lagrangian.free.fr/ariane_install_2.x.x_sep08.pdf + (python_packaging/pkg_structure: line 181) ok https://about.readthedocs.com/?ref=readthedocs.org + (python_packaging/pkg_structure: line 38) ok https://blog.ionelmc.ro/2014/05/25/python-packaging/ + (zzz_archival_docs/hg_version_control: line 41) ok https://bitbucket.org/ + ( contributing: line 21) ok https://app.readthedocs.org/projects/ubc-moad-docs/badge/?version=latest + ( globus: line 27) ok https://app.globus.org/file-manager + (git_version_control: line 60) ok https://brew.sh/ + (python_packaging/pkg_structure: line 39) ok https://bskinn.github.io/My-How-Why-Pyproject-Src/ + (python_packaging/pkg_structure: line 483) ok https://calver.org/ + (python_packaging/pkg_structure: line 296) ok https://click.palletsprojects.com/en/latest/ + (alliance-computing: line 85) redirect https://ccdb.alliancecan.ca/me/access_systems - with Found to https://ccdb.alliancecan.ca/security/login + ( contributing: line 46) ok https://app.readthedocs.org/projects/ubc-moad-docs/builds/ + ( xios-2: line 405) ok https://cfconventions.org/Data/cf-standard-names/29/build/cf-standard-name-table.html + (alliance-computing: line 55) ok https://ccdb.alliancecan.ca/account_application + ( analysis_repo: line 156) ok https://cookiecutter.readthedocs.io/en/latest/ + (python_packaging/pkg_structure: line 164) ok https://coverage.readthedocs.io/en/latest/ + (github_notebooks_readme: line 7) ok https://commonmark.org/ + ( contributing: line 13) ok https://creativecommons.org/licenses/by/4.0/ + (python_packaging/pkg_structure: line 745) ok https://doc.pytest.org/en/latest/explanation/goodpractices.html#tests-outside-application-code + (conda_pkg_env_mgr: line 39) ok https://conda-forge.org/ + ( vscode: line 15) ok https://code.visualstudio.com/ + ( jupyter: line 442) ok https://docs.alliancecan.ca/wiki/Anaconda/en + (alliance-computing: line 63) ok https://docs.alliancecan.ca/wiki/Apply_for_a_CCDB_account + (alliance-computing: line 120) ok https://docs.alliancecan.ca/wiki/SSH_Keys#Using_CCDB + (alliance-computing: line 72) ok https://docs.alliancecan.ca/wiki/Multifactor_authentication + (alliance-computing: line 69) ok https://docs.alliancecan.ca/wiki/Getting_started + ( jupyter: line 482) ok https://docs.alliancecan.ca/wiki/Python#Creating_and_using_a_virtual_environment + (python_packaging/pkg_structure: line 60) ok https://docs.conda.io/projects/conda/en/latest/ + (python_packaging/pkg_structure: line 773) ok https://docs.github.com/en/actions + ( contributing: line 77) ok https://docs.github.com/en/authentication/connecting-to-github-with-ssh + (conda_pkg_env_mgr: line 186) ok https://docs.conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html + (python_packaging/pkg_structure: line 778) ok https://docs.github.com/en/code-security/concepts/code-scanning/codeql/about-code-scanning-with-codeql + (conda_pkg_env_mgr: line 15) ok https://docs.conda.io/en/latest/ + ( ssh_access: line 506) ok https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account + (git_version_control: line 22) ok https://docs.github.com/en/get-started + (oceanparcels/index: line 23) ok https://docs.oceanparcels.org/en/latest/reference/predefined_kernels.html + ( contributing: line 13) ok https://docs.python.org/3/ + (python_packaging/pkg_structure: line 376) ok https://docs.readthedocs.com/platform/stable/config-file/v2.html + ( bash_config: line 43) ok https://douglatornell.github.io/2013-09-26-ubc/lessons/ref/shell.html + ( xios-2: line 160) ok https://en.wikipedia.org/wiki/XML + (python_packaging/pkg_structure: line 761) ok https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-security-updates + (python_packaging/pkg_structure: line 279) ok https://docs.openstack.org/cliff/latest/ + ( vscode: line 157) ok https://fortls.fortran-lang.org/index.html + ( contributing: line 434) ok https://git-scm.com/ + (git_version_control: line 22) ok https://git-scm.com/book/en/v2 + (git_version_control: line 22) ok https://git-scm.com/doc + (git_version_control: line 127) ok https://git-scm.com/docs/git-config + (git_version_control: line 56) ok https://git-scm.com/downloads + (git_version_control: line 213) ok https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository + (git_version_control: line 151) ok https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Setup-and-Config#ch_core_editor + ( getting_started: line 55) ok https://github.com/ + ( xios-2: line 297) ok https://forge.ipsl.fr/ioserver/raw-attachment/wiki/WikiStart/XIOS_user_guide.pdf + ( vcs_repos: line 19) ok https://github.com/MIDOSS/ + ( xios-2: line 15) ok https://forge.ipsl.fr/ioserver/wiki + ( sphinx_docs: line 36) ok https://github.com/MIDOSS/docs + (oceanparcels/index: line 21) ok https://github.com/Parcels-code/Parcels/discussions + ( vcs_repos: line 18) ok https://github.com/SalishSeaCast/ + ( analysis_repo: line 62) ok https://github.com/SalishSeaCast + ( xios-2: line 417) ok https://github.com/SalishSeaCast/SS-run-sets/tree/main/v201702 + ( xios-2: line 216) ok https://github.com/SalishSeaCast/SS-run-sets + ( xios-2: line 41) ok https://github.com/SalishSeaCast/XIOS-ARCH + (python_packaging/pkg_structure: line 24) ok https://github.com/SalishSeaCast/NEMO-Cmd + ( analysis_repo: line 33) ok https://github.com/SalishSeaCast/analysis-susan + (github_notebooks_readme: line 7) ok https://github.com/SalishSeaCast/analysis-ben/tree/master/notebooks + ( sphinx_docs: line 36) ok https://github.com/SalishSeaCast/docs + ( getting_started: line 55) ok https://github.com/UBC-MOAD + ( vcs_repos: line 17) ok https://github.com/UBC-MOAD/ + ( analysis_repo: line 316) ok https://github.com/SalishSeaCast/tools + ( sphinx_docs: line 79) ok https://github.com/UBC-MOAD/PythonNotes/blob/main/sphinx-docs/SphinxDocsTutorial.ipynb + (conda_pkg_env_mgr: line 31) ok https://github.com/UBC-MOAD/PythonNotes/blob/main/pkgs-envs/PythonPkgsEnvsSlides-2023.ipynb + ( contributing: line 13) ok https://github.com/UBC-MOAD/docs + (python_packaging/pkg_structure: line 296) ok https://github.com/UBC-MOAD/Reshapr + ( analysis_repo: line 51) ok https://github.com/UBC-MOAD/cookiecutter-analysis-repo + ( contributing: line 24) ok https://github.com/UBC-MOAD/docs/workflows/sphinx-linkcheck/badge.svg + ( contributing: line 460) ok https://github.com/UBC-MOAD/docs/blob/main/CONTRIBUTORS.rst + ( contributing: line 13) ok https://github.com/UBC-MOAD/docs/issues + (python_packaging/pkg_structure: line 799) ok https://github.com/UBC-MOAD/gha-workflows + ( sphinx_docs: line 36) ok https://github.com/UBC-MOAD/moad_tools + (python_packaging/pkg_structure: line 419) ok https://github.com/github/gitignore + (conda_pkg_env_mgr: line 39) ok https://github.com/conda-forge/miniforge + (python_packaging/pkg_structure: line 35) ok https://hatch.pypa.io/latest/ + (python_packaging/pkg_structure: line 202) ok https://hatch.pypa.io/latest/config/metadata/ + ( contributing: line 13) ok https://github.com/UBC-MOAD/docs/actions?query=workflow:sphinx-linkcheck + (git_version_control: line 215) ok https://github.com/github/gitignore/blob/main/Python.gitignore + ( jupyter: line 511) ok https://github.com/h5netcdf/h5netcdf + ( contributing: line 15) ok https://img.shields.io/badge/license-CC--BY-lightgrey.svg + ( contributing: line 30) ok https://img.shields.io/badge/python-3.14-blue.svg + ( contributing: line 18) ok https://img.shields.io/badge/version%20control-git-blue.svg?logo=github + ( contributing: line 89) ok https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json + (python_packaging/pkg_structure: line 37) ok https://hynek.me/articles/testing-packaging/ + ( jupyter: line 24) ok https://jupyter-notebook.readthedocs.io/en/stable/ + (github_notebooks_readme: line 12) ok https://jupyter.org/ + ( contributing: line 27) ok https://img.shields.io/github/issues/UBC-MOAD/docs?logo=github + ( ssh_access: line 71) ok https://learn.microsoft.com/en-ca/windows-server/administration/openssh/openssh_install_firstuse + ( vscode: line 123) ok https://marketplace.visualstudio.com/items?itemName=Digoro.Clipboard + (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/read/how-did-we-get-here.html + (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html + (zzz_archival_docs/hg_version_control: line 27) ok https://hgbook.red-bean.com/ + ( vscode: line 129) ok https://marketplace.visualstudio.com/items?itemName=fortran-lang.linter-gfortran + ( vscode: line 111) ok https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens + ( vscode: line 136) ok https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv + ( vscode: line 96) ok https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter-renderers + ( vscode: line 148) ok https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf + ( vscode: line 42) ok https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh + ( vscode: line 117) ok https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker + ( vscode: line 142) ok https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst + ( jupyter: line 120) ok https://marketplace.visualstudio.com/items?itemName=ms-python.python + (github_notebooks_readme: line 12) ok https://nbviewer.org/ + ( ariane: line 560) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/Ariane_Tracers.ipynb + (oceanparcels/index: line 24) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/OceanParcelsRecipes.ipynb + ( xios-2: line 26) ok https://nemo-cmd.readthedocs.io/en/latest/index.html#nemo-commandprocessor + ( xios-2: line 236) ok https://nemo-cmd.readthedocs.io/en/latest/run_description_file/3.6_yaml_file.html#output-section + ( python: line 20) ok https://numpy.org/ + ( ariane: line 195) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/ParticleTracking.ipynb + (python_packaging/pkg_structure: line 36) ok https://packaging.python.org/en/latest/ + (python_packaging/pkg_structure: line 67) ok https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-to-the-user-site + (oceanparcels/index: line 22) ok https://os.copernicus.org/articles/17/1067/2021/ + ( python: line 20) ok https://pandas.pydata.org/ + (oceanparcels/index: line 19) ok https://parcels-code.org/ + (oceanparcels/index: line 13) ok https://parcels-code.org/index.html + (python_packaging/pkg_structure: line 483) ok https://peps.python.org/pep-0440/ + (python_packaging/pkg_structure: line 53) ok https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs + ( contributing: line 87) ok https://pixi.prefix.dev/latest/ + (conda_pkg_env_mgr: line 30) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/pkgs-envs/PythonPkgsEnvsSlides-2023.ipynb + ( contributing: line 93) ok https://pixi.prefix.dev/latest/installation/ + ( jupyter: line 499) ok https://pypi.org/ + ( python: line 51) ok https://realpython.com/ + ( sphinx_docs: line 183) ok https://rhodesmill.org/brandon/2012/one-sentence-per-line/ + (python_packaging/pkg_structure: line 183) ok https://pre-commit.com/ + (alliance-computing: line 248) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#compilenemo-3-6-nibi + (alliance-computing: line 242) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#installcommandprocessorpackages + (alliance-computing: line 238) ok https://salishsea-meopar-docs.readthedocs.io/en/latest/code-notes/salishsea-nemo/quickstart/nibi.html#createworkspaceandclonerepositories + ( analysis_repo: line 320) ok https://salishsea-meopar-tools.readthedocs.io/en/latest/SalishSeaTools/index.html + ( analysis_repo: line 320) ok https://salishsea-meopar-tools.readthedocs.io/en/latest/visualisation/visualization_workflows_xarray.html + (alliance-computing: line 242) ok https://salishseacmd.readthedocs.io/en/latest/index.html#salishseacmdprocessor + ( xios-2: line 236) ok https://salishseacmd.readthedocs.io/en/latest/run_description_file/3.6_yaml_file.html#output-section + (oceanparcels/index: line 20) ok https://salishseacast.slack.com/?redir=%2Farchives%2FC02ETTPHFPX + (git_version_control: line 151) ok https://salishseacast.slack.com/?redir=%2Farchives%2FCFR6VU70S + ( sphinx_docs: line 78) ok https://nbviewer.org/github/UBC-MOAD/PythonNotes/blob/main/sphinx-docs/SphinxDocsTutorial.ipynb + (python_packaging/pkg_structure: line 40) ok https://snarky.ca/clarifying-pep-518/ + ( bash_config: line 43) ok https://software-carpentry.org/ + (zzz_archival_docs/hg_version_control: line 48) ok https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/ + (python_packaging/pkg_structure: line 826) ok https://tox.wiki/en/latest/ + ( contributing: line 13) ok https://ubc-moad-docs.readthedocs.io/en/latest/ + ( sphinx_docs: line 50) ok https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html#documentation-with-sphinx + ( sphinx_docs: line 88) ok https://ubc-moad-tools.readthedocs.io/en/latest/pkg_development.html#moad-toolspackageddevelopment + (zzz_archival_docs/hg_version_control: line 75) ok https://tortoisehg.bitbucket.io/ + (zzz_archival_docs/hg_version_control: line 27) ok https://wiki.mercurial-scm.org/BeginnersGuides + (zzz_archival_docs/hg_version_control: line 248) ok https://wiki.mercurial-scm.org/RebaseExtension#Scenario_A + (zzz_archival_docs/hg_version_control: line 248) ok https://wiki.mercurial-scm.org/RebaseExtension + (zzz_archival_docs/hg_version_control: line 262) ok https://wiki.mercurial-scm.org/RebaseExtension#Scenarios + (conda_pkg_env_mgr: line 15) ok https://www.anaconda.com/download + ( ariane: line 787) ok https://nbviewer.org/github/SalishSeaCast/analysis/blob/master/Idalia/Ariane_TimeRes.ipynb + (python_packaging/pkg_structure: line 355) ok https://www.apache.org/licenses/ + ( CONTRIBUTORS: line 7) ok https://www.eoas.ubc.ca/~sallen/ + ( ssh_access: line 31) ok https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server + ( globus: line 15) ok https://www.globus.org/data-transfer + ( sphinx_docs: line 19) ok https://www.mathjax.org/ + (alliance-computing: line 15) ok https://www.alliancecan.ca/en + ( python: line 15) ok https://www.python.org/ + (zzz_archival_docs/hg_version_control: line 63) ok https://www.mercurial-scm.org/install + (zzz_archival_docs/hg_version_control: line 21) ok https://www.mercurial-scm.org/ + (zzz_archival_docs/hg_version_control: line 75) ok https://www.sourcetreeapp.com/ + ( contributing: line 121) ok https://www.sphinx-doc.org/en/master/ + ( sphinx_docs: line 19) ok https://www.latex-project.org/ + (python_packaging/pkg_structure: line 702) ok https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + (python_packaging/pkg_structure: line 787) ok https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder + (python_packaging/pkg_structure: line 702) ok https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports + ( sphinx_docs: line 260) ok https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx + (zzz_archival_docs/hg_version_control: line 208) ok https://www.selenic.com/mercurial/hgignore.5.html + (zzz_archival_docs/hg_version_control: line 171) ok https://www.selenic.com/mercurial/hgrc.5.html + ( contributing: line 121) ok https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html + ( sphinx_docs: line 57) ok https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html + ( python: line 20) ok https://www.tomasbeuzen.com/python-programming-for-data-science/README.html + ( python: line 20) ok https://www.tomasbeuzen.com/ + ( xios-2: line 199) ok https://www.xmlvalidation.com/ + build succeeded. + + Look for any errors in the above output or in _build/linkcheck/output.txt :command:`make linkcheck` is run monthly via a `scheduled GitHub Actions workflow`_ diff --git a/git_version_control.rst b/git_version_control.rst index a66b4af..9ce4e0d 100644 --- a/git_version_control.rst +++ b/git_version_control.rst @@ -89,14 +89,14 @@ The :command:`git config --global` command is how you interact with the :file:`$ Start by telling Git who you are. It will include this information as part of the metadata in every commit you make. -.. code-block:: bash +.. code-block:: console $ git config --global user.name "Your Name" $ git config --global user.email "you@example.com" Also do: -.. code-block:: bash +.. code-block:: console $ git config --global init.defaultbranch main $ git config --global pull.rebase true @@ -116,9 +116,9 @@ We just have to tell Git what to do by default after :command:`git pull` so that If you want to see what is in your :file:`$HOME/.gitconfig` file, you can use: -.. code-block:: bash +.. code-block:: console - git config --global --list + $ git config --global --list You can also have per-repository config files that are stored in the :file:`.git/config` file in a repo. You interact with that file with :command:`git config --local`. @@ -144,7 +144,7 @@ Git opens :program:`vi`. If you prefer to use a different editor, you can tell Git that with: -.. code-block:: bash +.. code-block:: console $ git config --global core.editor "your favourite editor" @@ -166,7 +166,7 @@ You can also use :command:`git config` to create aliases for complicated Git com or commands that you want to give a short name to. Here are some examples: -.. code-block:: bash +.. code-block:: console $ git config --global alias.glog "log --graph" @@ -174,7 +174,7 @@ This makes :command:`git glog` show you an ASCII-art graph version of the log of The graph shows branches that have diverged and merged. Mercurial users who relied on :command:`hg glog` will find this alias comforting. -.. code-block:: bash +.. code-block:: console $ git config --global alias.out "log --pretty=oneline --abbrev-commit --graph @{u}.." @@ -182,7 +182,7 @@ makes :command:`git out` show you the commits that you have made locally but not You can get more information about the changes in each of those commits by adding the ``--stat`` option; i.e. :command:`git out --stat`. -.. code-block:: bash +.. code-block:: console $ git config --global alias.in '!git fetch && git log --pretty=oneline --abbrev-commit --graph ..@{u}' diff --git a/github_notebooks_readme.rst b/github_notebooks_readme.rst index 63e6327..cbc433c 100644 --- a/github_notebooks_readme.rst +++ b/github_notebooks_readme.rst @@ -45,7 +45,7 @@ Here is a prototype :file:`make_readme.py` module that provides that automation: or change the description of a notebook in its first Markdown cell, please generate a updated `README.md` file with: - python3 -m make_readme + python -m make_readme and commit and push the updated `README.md` to GitHub. """ @@ -201,9 +201,9 @@ Here's how to set up and use this script: #. Run the :file:`make_readme.py` script to create your :file:`README.md` file: - .. code-block:: bash + .. code-block:: console - $ python3 -m make_readme + $ python -m make_readme #. Use Git to add, commit, @@ -211,7 +211,7 @@ Here's how to set up and use this script: the :file:`make_readme.py` script, and the :file:`README.md` file: - .. code-block:: bash + .. code-block:: console $ git add make_readme.py README.md MyNotebook.ipynb $ git commit -m"Add new notebook, make_readme script and README file." @@ -220,12 +220,12 @@ Here's how to set up and use this script: #. Use your browser to navigate to the repository and directory on GitHub and you should see the rendered :file:`README.md` showing your notebook name(s) as a link to the nbviewer rendering(s) for your notebook(s). #. Each time you create a new notebook in the directory, - run :command:`python3 -m make_readme` to update the :file:`README.md` file and commit it along with your new notebook. + run :command:`python -m make_readme` to update the :file:`README.md` file and commit it along with your new notebook. The :file:`make_readme.py` script reads the first cell of each notebook in the directory and, if that cell contains text, adds it to the :file:`README.md` file. That lets you include a title and brief description of your notebooks along with the links on the GitHub page. -If you change the contents of that 1st cell in an existing notebook you need to run :command:`python3 -m make_readme`, +If you change the contents of that 1st cell in an existing notebook you need to run :command:`python -m make_readme`, commit the :file:`README.md` changes, and push them to GitHub in order to update the page there. diff --git a/jupyter.rst b/jupyter.rst index 5da28c4..5b46241 100644 --- a/jupyter.rst +++ b/jupyter.rst @@ -133,7 +133,7 @@ For example, if you are working in your analysis repo, the commands would be like: -.. code-block:: bash +.. code-block:: console $ conda activate analysis-doug (analysis-doug)$ cd analysis-doug/ @@ -144,13 +144,16 @@ You have to keep it open until you are finished with Jupyter and want to shut it The client part of Jupyter should have opened in a new browser tab. If not, -follow the instructions in the terminal window that say something like:: +follow the instructions in the terminal window that say something like: - To access the notebook, open this file in a browser: +.. code-block:: output + :class: no-copybutton + + To access the notebook, open this file in a browser: file:///home/doug/.local/share/jupyter/runtime/nbserver-3581193-open.html - Or copy and paste one of these URLs: + Or copy and paste one of these URLs: http://localhost:8889/?token=f8b14419fc17ff93240a914930566fad4c2f69f064d4fdb9 - or http://127.0.0.1:8889/?token=f8b14419fc17ff93240a914930566fad4c2f69f064d4fdb9 + or http://127.0.0.1:8889/?token=f8b14419fc17ff93240a914930566fad4c2f69f064d4fdb9 For the older ``notebook`` interface, the instructions are much the same, @@ -274,7 +277,7 @@ To start the :command:`jupyter lab` server on ``salish``, open a terminal window on your laptop, and use :program:`ssh` to start a command-line session on ``salish``: -.. code-block:: bash +.. code-block:: console $ ssh salish @@ -285,7 +288,7 @@ For example, if you are working in your analysis repo, the commands would be like: -.. code-block:: bash +.. code-block:: console $ cd analysis-doug/ $ jupyter lab --no-browser --ip $(hostname -f) @@ -296,7 +299,8 @@ The ``--ip $(hostname -f)`` causes the name of the machine you are running the s You should see output in that terminal window that looks something like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton [I 09:30:01.331 LabApp] JupyterLab extension loaded from /home/dlatorne/conda_envs/dask-expts/lib/python3.8/site-packages/jupyterlab [I 09:30:01.332 LabApp] JupyterLab application directory is /home/dlatorne/conda_envs/dask-expts/share/jupyter/lab @@ -321,9 +325,12 @@ You should see output in that terminal window that looks something like: The URLs on the last 2 lines are the important bit that we need to use to get the client running on our laptop. The second last one that contains the name of the machine that the server is running on is the important one for the rest of this setup. -That is:: +That is: + +.. code-block:: output + :class: no-copybutton - http://salish:8888/?token=bbd686ffaa5398aacaee25c9fa44b5f9424889a81ad7d9f1 + http://salish:8888/?token=bbd686ffaa5398aacaee25c9fa44b5f9424889a81ad7d9f1 in the example output above. @@ -340,7 +347,7 @@ To set up the :program:`ssh` tunnel, open a new terminal window on your laptop, and enter the command: -.. code-block:: bash +.. code-block:: console $ ssh -N -L 4343:salish:8888 salish @@ -372,9 +379,12 @@ You may land on a Jupyter page that asks you to enter a :guilabel:`Password or t If so, copy the the long string of digits and letters from the URL in the Jupyter server terminal windows. For example, -the in the URL:: +the in the URL: + +.. code-block:: output + :class: no-copybutton - http://sailsh:8888/?token=bbd686ffaa5398aacaee25c9fa44b5f9424889a81ad7d9f1 + http://sailsh:8888/?token=bbd686ffaa5398aacaee25c9fa44b5f9424889a81ad7d9f1 the token is ``bbd686ffaa5398aacaee25c9fa44b5f9424889a81ad7d9f1``. @@ -451,13 +461,13 @@ Use the Compute Canada module system to load Python, preferably the most recent available version. On ``graham`` in Dec-2022 that is Python 3.10.2: -.. code-block:: bash +.. code-block:: console $ module load python/3.10.2 Create a Python virtualenv in which to install ``jupyterlab`` and other packages: -.. code-block:: bash +.. code-block:: console $ python3 -m virtualenv --no-download ~/venvs/jupyter @@ -471,7 +481,7 @@ This virtual environment will be created in the :file:`$HOME/venvs/jupyter/`. Activate the venv with: -.. code-block:: bash +.. code-block:: console $ source ~/venvs/jupyter/bin/activate @@ -484,7 +494,7 @@ This rarely seems to have any effect, but it is recommended in the `Compute Canada venv docs`_, so we do it: -.. code-block:: bash +.. code-block:: console (jupyter)$ python3 -m pip install --no-index --upgrade pip @@ -492,7 +502,7 @@ so we do it: Install the ``jupyterlab`` package and other packages that we routinely use for analysis into the venv: -.. code-block:: bash +.. code-block:: console (jupyter)$ python3 -m pip install jupyterlab xarray h5netcdf bottleneck matplotlib cmocean @@ -528,7 +538,7 @@ they are installed from PyPI. perhaps to activate a venv with a different collection of packages installed, use: - .. code-block:: bash + .. code-block:: console (jupyter)$ deactivate @@ -541,7 +551,7 @@ Running :command:`jupyter lab` in an Interactive Compute Session In an :program:`ssh` session on ``nibi``, start an interactive session on a compute node with: -.. code-block:: bash +.. code-block:: console $ salloc --time=1:00:00 --ntasks=1 --cpus-per-task=2 --mem-per-cpu=1024M --account=rrg-allen @@ -553,7 +563,8 @@ On other clusters use ``--account=def-allen``. You should see output something like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton salloc: Pending job allocation 40482784 salloc: job 40482784 queued and waiting for resources @@ -572,7 +583,7 @@ Eventually, your command-line prompt should re-appear showing that you are now connected to one of the compute nodes, ``c705`` in this case: -.. code-block:: bash +.. code-block:: console [your-user-id@c705 ~]$ @@ -581,7 +592,7 @@ Load a Alliance Python language module, and activate the Python virtual environment in which ``jupyterlab`` and the other packages that you need are installed. In this example we load Python 3.8.2 and activate our environment from the :file:`~/venvs/jupyter/` directory: -.. code-block:: bash +.. code-block:: console $ module load python/3.8.2 $ source ~/venvs/jupyter/bin/activate @@ -592,7 +603,7 @@ For example, if you are working in your analysis repo, the commands would be like: -.. code-block:: bash +.. code-block:: console (jupyter) [dlatorne@gra581 ~]$ cd $PROJECT/MEOPAR/analysis-doug/ (jupyter) [dlatorne@gra581 ~]$ jupyter lab --no-browser --ip $(hostname -f) @@ -603,7 +614,8 @@ The ``--ip $(hostname -f)`` causes the name of the node you are running the serv You should see output in that terminal window that looks something like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton [I 17:26:04.998 LabApp] Writing notebook server cookie secret to /home/dlatorne/.local/share/jupyter/runtime/notebook_cookie_secret [I 17:26:07.186 LabApp] JupyterLab extension loaded from /home/dlatorne/venvs/jupyter/lib/python3.8/site-packages/jupyterlab @@ -629,9 +641,12 @@ You should see output in that terminal window that looks something like: The URLs on the last 2 lines are the important bit that we need to use to get the client running on our laptop. The second last one that contains the name of the node that the server is running on is the important one for the rest of this setup. -That is:: +That is: - http://c705.nibi.sharcnet:8888/?token=327caed3d832eefaad25a57cbf01de9f42685ced4306e036 +.. code-block:: output + :class: no-copybutton + + http://c705.nibi.sharcnet:8888/?token=327caed3d832eefaad25a57cbf01de9f42685ced4306e036 in the example output above. @@ -650,7 +665,7 @@ To set up the :program:`ssh` tunnel, open a new terminal window on your laptop, and enter the command: -.. code-block:: bash +.. code-block:: console $ ssh -N -L 4343:c705.nibi.sharcnet:8888 nibi @@ -678,9 +693,12 @@ You may land on a Jupyter page that asks you to enter a :guilabel:`Password or t If so, copy the the long string of digits and letters from the URL in the Jupyter server terminal windows. For example, -the in the URL:: +the in the URL: + +.. code-block:: output + :class: no-copybutton - http://c705.nibi.sharcnet:8888/?token=327caed3d832eefaad25a57cbf01de9f42685ced4306e036 + http://c705.nibi.sharcnet:8888/?token=327caed3d832eefaad25a57cbf01de9f42685ced4306e036 the token is ``327caed3d832eefaad25a57cbf01de9f42685ced4306e036``. diff --git a/pixi.lock b/pixi.lock index 9ff51f4..38b902e 100644 --- a/pixi.lock +++ b/pixi.lock @@ -100,6 +100,7 @@ environments: - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.3-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-8.1.3-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-notfound-page-1.0.4-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-rtd-theme-3.0.0-hd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx_rtd_theme-3.0.0-pyha770c72_0.conda @@ -211,6 +212,7 @@ environments: - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.3-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-8.1.3-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-notfound-page-1.0.4-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-rtd-theme-3.0.0-hd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx_rtd_theme-3.0.0-pyha770c72_0.conda @@ -323,6 +325,7 @@ environments: - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.3-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-8.1.3-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-notfound-page-1.0.4-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-rtd-theme-3.0.0-hd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx_rtd_theme-3.0.0-pyha770c72_0.conda @@ -431,6 +434,7 @@ environments: - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.3-pyhd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-8.1.3-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-notfound-page-1.0.4-pyhd8ed1ab_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-rtd-theme-3.0.0-hd8ed1ab_0.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx_rtd_theme-3.0.0-pyha770c72_0.conda @@ -2448,6 +2452,18 @@ packages: - pkg:pypi/sphinx?source=hash-mapping size: 1387076 timestamp: 1733754175386 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda + sha256: 8cd892e49cb4d00501bc4439fb0c73ca44905f01a65b2b7fa05ba0e8f3924f19 + md5: bf22cb9c439572760316ce0748af3713 + depends: + - python >=3.9 + - sphinx >=1.8 + license: MIT + license_family: MIT + purls: + - pkg:pypi/sphinx-copybutton?source=hash-mapping + size: 17893 + timestamp: 1734573117732 - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-notfound-page-1.0.4-pyhd8ed1ab_1.conda sha256: 96be04bfbc575cd28c0739bd2b938489599c2f208e4889ffa70ece0c447083d2 md5: 5947f4433b325b8e7f98fd8370d7a716 diff --git a/pixi.toml b/pixi.toml index b6dcf28..3c93324 100644 --- a/pixi.toml +++ b/pixi.toml @@ -21,6 +21,7 @@ nbsphinx = "==0.9.5" sphinx = "==8.1.3" sphinx-notfound-page = "==1.0.4" sphinx-rtd-theme = "==3.0.0" +sphinx-copybutton = ">=0.5.2,<0.6" [pypi-dependencies] # For build on readthedocs diff --git a/python_packaging/pkg_structure.rst b/python_packaging/pkg_structure.rst index e592aab..ac2dacd 100644 --- a/python_packaging/pkg_structure.rst +++ b/python_packaging/pkg_structure.rst @@ -78,7 +78,8 @@ Package Layout Using the `NEMO-Cmd`_ package as an example, the directories and files layout of a MOAD package looks like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton NEMO-Cmd/ ├── docs/ diff --git a/requirements.txt b/requirements.txt index a42ab40..1d27364 100644 --- a/requirements.txt +++ b/requirements.txt @@ -66,6 +66,7 @@ six==1.17.0 snowballstemmer==3.0.1 soupsieve==2.8.3 Sphinx==8.1.3 +sphinx-copybutton==0.5.2 sphinx-notfound-page==1.0.4 sphinx_rtd_theme==3.0.0 sphinxcontrib-applehelp==2.0.0 @@ -77,7 +78,7 @@ sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==1.1.10 tinycss2==1.5.1 tomli==2.4.0 -tornado==6.5.3 +tornado==6.5.4 traitlets==5.14.3 typing_extensions==4.15.0 ukkonen==1.0.1 diff --git a/sphinx_docs.rst b/sphinx_docs.rst index 21a5c64..cd5c046 100644 --- a/sphinx_docs.rst +++ b/sphinx_docs.rst @@ -105,9 +105,9 @@ In the top level :file:`docs/` directory or the :file:`docs/` sub-directory in a code repository) use the command: -.. code-block:: bash +.. code-block:: console - make clean html + $ make clean html to build the docs. You will be notified of any syntax or consistency errors. @@ -116,9 +116,9 @@ The HTML pages produced by the :command:`make clean html` command are stored in You can use your browser to open the :file:`index.html` file in that directory to preview them. The command: -.. code-block:: bash +.. code-block:: console - firefox _build/html/index.html + $ firefox _build/html/index.html will probably do the right thing. You can keep a browser tab open to the rendered docs and refresh after each build to see updates. @@ -134,33 +134,36 @@ You can keep a browser tab open to the rendered docs and refresh after each buil and the directory :file:`_static/`. After the docs have been built it will also contain the :file:`_build/` sub-directory. -The result of running :command:`make clean html` should look something like:: - - Removing everything under '_build'... - Running Sphinx v3.5.2 - making output directory... done - loading intersphinx inventory from https://ubc-moad-tools.readthedocs.io/en/latest/objects.inv... - loading intersphinx inventory from https://nemo-cmd.readthedocs.io/en/latest/objects.inv... - loading intersphinx inventory from https://salishseacmd.readthedocs.io/en/latest/objects.inv... - loading intersphinx inventory from https://salishsea-meopar-docs.readthedocs.io/en/latest/objects.inv... - building [mo]: targets for 0 po files that are out of date - building [html]: targets for 20 source files that are out of date - updating environment: [new config] 20 added, 0 changed, 0 removed - reading sources... [100%] zzz_archival_docs/index - looking for now-outdated files... none found - pickling environment... done - checking consistency... done - preparing documents... done - writing output... [100%] zzz_archival_docs/index - generating indices... done - writing additional pages... search done - copying static files... done - copying extra files... done - dumping search index in English (code: en)... done - dumping object inventory... done - build succeeded. - - The HTML pages are in _build/html. +The result of running :command:`make clean html` should look something like: + +.. code-block:: output + :class: no-copybutton + + Removing everything under '_build'... + Running Sphinx v3.5.2 + making output directory... done + loading intersphinx inventory from https://ubc-moad-tools.readthedocs.io/en/latest/objects.inv... + loading intersphinx inventory from https://nemo-cmd.readthedocs.io/en/latest/objects.inv... + loading intersphinx inventory from https://salishseacmd.readthedocs.io/en/latest/objects.inv... + loading intersphinx inventory from https://salishsea-meopar-docs.readthedocs.io/en/latest/objects.inv... + building [mo]: targets for 0 po files that are out of date + building [html]: targets for 20 source files that are out of date + updating environment: [new config] 20 added, 0 changed, 0 removed + reading sources... [100%] zzz_archival_docs/index + looking for now-outdated files... none found + pickling environment... done + checking consistency... done + preparing documents... done + writing output... [100%] zzz_archival_docs/index + generating indices... done + writing additional pages... search done + copying static files... done + copying extra files... done + dumping search index in English (code: en)... done + dumping object inventory... done + build succeeded. + + The HTML pages are in _build/html. .. _LinkCheckingDocumentation: @@ -170,9 +173,9 @@ Link Checking the Documentation You can also check the documentation for broken links with the command: -.. code-block:: bash +.. code-block:: console - make clean linkcheck + $ make clean linkcheck Look for any errors in the output or in the :file:`_build/linkcheck/output.txt` file. @@ -195,11 +198,13 @@ Links and Cross-references External Links -------------- -The preferred way to including external links is via markup like:: +The preferred way to including external links is via markup like: - This is a paragraph that contains `a link`_. +.. code-block:: reStructuredText - .. _a link: http://example.com/ + This is a paragraph that contains `a link`_. + + .. _a link: http://example.com/ If the link text should be the web address, you don't need special markup at all, @@ -216,29 +221,33 @@ There are three ways in which you can refer to labels: #. If you place a label directly before a section title, you can reference to it with ``:ref:`label-name```. - Example:: + Example: + + .. code-block:: reStructuredText - .. _my-reference-label: + .. _my-reference-label: - Section to cross-reference - -------------------------- + Section to cross-reference + -------------------------- - This is the text of the section. + This is the text of the section. - It refers to the section itself, see :ref:`my-reference-label`. + It refers to the section itself, see :ref:`my-reference-label`. The ``:ref:`` role would then generate a link to the section, with the link title being "Section to cross-reference". This works just as well when sections and references are in different source files. Labels also work with figures. - Given:: + Given: - .. _my-figure: + .. code-block:: reStructuredText - .. figure:: whatever + .. _my-figure: - Figure caption + .. figure:: whatever + + Figure caption a reference ``:ref:`my-figure``` would insert a reference to the figure with link text "Figure caption". @@ -251,16 +260,20 @@ There are three ways in which you can refer to labels: using this syntax: ``:ref:`Link title ```. The same syntax can be used to change the link text from what it would be automatically to something different that you want in a specific context. - Example:: + Example: + + .. code-block:: reStructuredText - :ref:`the section above ` + :ref:`the section above ` makes a link to the ``Section to cross-reference`` section with ``the section above`` as the link text. #. The `intersphinx`_ extension automatically generates links to labels and objects in Sphinx docs in other repositories. - Example:: + Example: - :ref:`moadtools:moad_toolsPackagedDevelopment` + .. code-block:: reStructuredText + + :ref:`moadtools:moad_toolsPackagedDevelopment` creates a link to the :ref:`moadtools:moad_toolsPackagedDevelopment` section in the `UBC-MOAD/moad_tools`_ docs. @@ -273,11 +286,13 @@ and when section headings are changed. Links to Rendered Jupyter Notebooks ----------------------------------- -To link to a rendered representation of an Jupyter Notebook that has been pushed to a GitHub repo use markup like:: +To link to a rendered representation of an Jupyter Notebook that has been pushed to a GitHub repo use markup like: + +.. code-block:: reStructuredText - * `SalishSeaBathy.ipynb`_: Documents the full domain bathymetry used for the Salish Sea NEMO runs. + * `SalishSeaBathy.ipynb`_: Documents the full domain bathymetry used for the Salish Sea NEMO runs. - .. _SalishSeaBathy.ipynb: https://nbviewer.org/github/SalishSeaCast/tools/blob/main/bathymetry/SalishSeaBathy.ipynb + .. _SalishSeaBathy.ipynb: https://nbviewer.org/github/SalishSeaCast/tools/blob/main/bathymetry/SalishSeaBathy.ipynb Forcing Line Breaks @@ -292,19 +307,21 @@ etc. Occasionally though you may need to force line breaks. The most common case for this is to add line breaks within table cells so as as to avoid excessive sideways scrolling of the rendered table. You can force a line break in the HTML that Sphinx renders by defining a substitution that will insert a break tag (`
`). -Here's an example of doing that and using the substitution in a table cell:: +Here's an example of doing that and using the substitution in a table cell: + +.. code-block:: reStructuredText - .. |br| raw:: html + .. |br| raw:: html -
+
- =========== =================================================== ============== ================== - Date Change New Value Changeset - =========== =================================================== ============== ================== - 27-Oct-2014 1st :file:`nowcast/` run results N/A - 20-Nov-2014 1st :file:`forecast/` run results N/A - 26-Nov-2014 Changed to tidal forcing tuned for better |br| see changeset efa8c39a9a7c_ - accuracy at Point Atkinson - =========== =================================================== ============== ================== + =========== =================================================== ============== ================== + Date Change New Value Changeset + =========== =================================================== ============== ================== + 27-Oct-2014 1st :file:`nowcast/` run results N/A + 20-Nov-2014 1st :file:`forecast/` run results N/A + 26-Nov-2014 Changed to tidal forcing tuned for better |br| see changeset efa8c39a9a7c_ + accuracy at Point Atkinson + =========== =================================================== ============== ================== .. note:: The ``|br|`` substitution needs to be defined once (but *only* once) per file. diff --git a/ssh_access.rst b/ssh_access.rst index 5fcc400..eb39abe 100644 --- a/ssh_access.rst +++ b/ssh_access.rst @@ -97,13 +97,14 @@ Here we tell it to use the Ed25519 algorithm to create the keys. Open your Terminal program to get a command-line interface, and type the command: -.. code-block:: bash +.. code-block:: console $ ssh-keygen -t ed25519 The output should look like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Generating public/private rsa key pair. Enter file in which to save the key (/home/username/.ssh/id_ed25519): @@ -116,7 +117,8 @@ Hit enter to accept the default key file path and name. If you get a message like: - .. code-block:: text + .. code-block:: output + :class: no-copybutton /home/username/.ssh/id_ed25519 already exists. Overwrite (y/n)? @@ -126,7 +128,8 @@ Hit enter to accept the default key file path and name. You might see the message: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Created directory '/home/username/.ssh'. @@ -135,7 +138,8 @@ then, for sure, you should see the message: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Enter passphrase (empty for no passphrase): @@ -157,13 +161,15 @@ and that you won't have to type it very often... But you will have to type it again after the next prompt :-) -.. code-block:: text +.. code-block:: output + :class: no-copybutton Enter same passphrase again: When the key pair generation is finished you should see output like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Your identification has been saved in /home/username/.ssh/id_ed25519 Your public key has been saved in /home/username/.ssh/id_ed25519.pub @@ -216,7 +222,7 @@ We'll use :command:`nano` here because it is available almost everywhere. Open the file with :command:`nano`: -.. code-block:: bash +.. code-block:: console $ nano ~/.ssh/config @@ -334,15 +340,15 @@ Your file should now look like: Now, instead of having to type: -.. code-block:: text +.. code-block:: console - ssh username@salish.eos.ubc.ca + $ ssh username@salish.eos.ubc.ca you will be able to type: -.. code-block:: text +.. code-block:: console - ssh salish + $ ssh salish (after we complete 1 more step of setup). @@ -360,14 +366,15 @@ The command to do that is :command:`ssh-copy-id`. Copy your public key to ``salish`` with: -.. code-block:: bash +.. code-block:: console $ ssh-copy-id salish That command will use the information you put into :file:`~/.ssh/config` to expand ``salish`` to ``username@salish.eos.ca``. It should produce output like: -.. code-block:: text +.. code-block:: output + :class: no-copybutton /usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/username/.ssh/id_ed25519.pub" The authenticity of host 'salish.eos.ca (142.103.36.12)' can't be established. @@ -378,7 +385,8 @@ Type ``yes`` to proceed. The output from :command:`ssh-copy-id` should continue with: -.. code-block:: text +.. code-block:: output + :class: no-copybutton /usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed /usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys @@ -387,7 +395,8 @@ The output from :command:`ssh-copy-id` should continue with: Type in your EOAS Linux systems password sent to you by EOAS IT, and the output from :command:`ssh-copy-id` should finish with: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Number of key(s) added: 1 @@ -398,14 +407,15 @@ Now, as the output says, test the authentication with: -.. code-block:: bash +.. code-block:: console $ ssh salish Your ssh agent should ask you for your passphrase so that it can decrypt your private key, then you should find yourself at the command-line prompt on ``salish``: -.. code-block:: text +.. code-block:: output + :class: no-copybutton Welcome to Ubuntu 18.04.6 LTS (GNU/Linux 5.4.0-121-generic x86_64) @@ -452,25 +462,25 @@ The first step is to connect to one of the Linux machines in Waterhole Connect to ``chum``: -.. code-block:: bash +.. code-block:: console $ ssh chum Then, navigate to your :file:`.ssh/` path: -.. code-block:: bash +.. code-block:: console $ cd .ssh/ Create a new file named :file:`authorized_keys` : -.. code-block:: bash +.. code-block:: console $ touch authorized_keys Open the file named :file:`authorized_keys` with :command:`nano` to edit it: -.. code-block:: bash +.. code-block:: console $ nano authorized_keys @@ -484,7 +494,7 @@ As a last step, we need to add the private key into the SSH authentication agent .. code-block:: pwsh - ssh-add $env:USERPROFILE\.ssh\id_ed25519 + PS> ssh-add $env:USERPROFILE\.ssh\id_ed25519 Disconnect from ``chum`` with ``exit``, and connect again with ``ssh chum``. This time you should connect without being asked for your password or your passphrase. @@ -540,7 +550,7 @@ To get a short reminder of the option flags for any of these commands use the ``--help`` option; e.g. -.. code-block:: bash +.. code-block:: console $ ssh --help @@ -549,7 +559,7 @@ To get a detailed description of a command use the :command:`man` command; e.g. -.. code-block:: bash +.. code-block:: console $ man scp @@ -571,14 +581,14 @@ Most often you will use :command:`ssh` to open a terminal session on a remote computer; e.g. -.. code-block:: bash +.. code-block:: console $ ssh salish You can also use :command:`ssh` to execute a command on a remote computer without actually opening the terminal session; e.g. -.. code-block:: bash +.. code-block:: console $ ssh salish ls -lh /results2/SalishSea/nowcast-green.201905/09sep20/ @@ -590,7 +600,7 @@ of the files in the directory there called :file:`/results2/SalishSea/nowcast-gr If you get too fancy with the command that you want to execute remotely you may have to enclose it in quotes to prevent your local shell from messing it up; e.g. -.. code-block:: bash +.. code-block:: console $ ssh salish "find /results/forcing/atmospheric/GEM2.5/GRIB/20200909/12 -type f | wc -l" @@ -598,7 +608,7 @@ If you have trouble with :command:`ssh` not making a connection, you can tell it to output debugging messages its progress by using the ``-v`` option; e.g. -.. code-block:: bash +.. code-block:: console $ ssh -v salish @@ -632,7 +642,7 @@ or between two remote machines without bringing the file to your local machine. To copy a file from your current directory on your local computer to your home directory on ``salish`` use: -.. code-block:: bash +.. code-block:: console $ scp my-local-file salish: @@ -643,7 +653,7 @@ all of those files will get copied to ``salish``. To copy a file from your current directory on your local computer to your ``/ocean/$USER/`` space on :command:`salish` use: -.. code-block:: bash +.. code-block:: console $ scp my-local-file "salish:/ocean/$USER/" @@ -651,7 +661,7 @@ The quotes around ``"salish:/ocean/$USER/"`` are necessary to prevent your local To copy a file from your ``/ocean/$USER/`` space on ``salish`` to your current directory on your local computer use: -.. code-block:: bash +.. code-block:: console $ scp "salish:/ocean/$USER/my-remote-file" ./ @@ -666,7 +676,7 @@ If you have trouble with :command:`scp` not making a connection, you can tell it to output debugging messages its progress by using the ``-v`` option; e.g. -.. code-block:: bash +.. code-block:: console $ scp -v my-local-file salish: @@ -701,7 +711,7 @@ or Google for more information about how to use :command:`sftp`. Here is a sample :command:`sftp` session to copy a file from your scratch space on ``salish`` to your current directory on your local computer: -.. code-block:: text +.. code-block:: console $ sftp salish Connected to salish. @@ -716,7 +726,7 @@ If you have trouble with :command:`sftp` not making a connection, you can tell it to output debugging messages its progress by using the ``-v`` option; e.g. -.. code-block:: bash +.. code-block:: console $ sftp -v salish diff --git a/vscode.rst b/vscode.rst index 026971d..6b192fc 100644 --- a/vscode.rst +++ b/vscode.rst @@ -171,15 +171,16 @@ etc.: create a conda environment called ``fortls`` with the ``fortls`` package and its dependencies installed in it: - .. code-block:: bash + .. code-block:: console - conda create -n fortls fortls + $ conda create -n fortls fortls #. Confirm the path of that new ``fortls`` environment by looking at the output of :command:`conda env list`. You should see a line like: - .. code-block:: text + .. code-block:: output + :class: no-copybutton fortls /home/dlatorne/miniforge3/envs/fortls diff --git a/xios-2.rst b/xios-2.rst index dc5e8cf..3e688f1 100644 --- a/xios-2.rst +++ b/xios-2.rst @@ -60,21 +60,21 @@ and build XIOS-2 on any of the other Alliance clusters. ``nibi`` -------- -.. code-block:: bash +.. code-block:: console - cd $HOME/MEOPAR/ - git clone git@github.com:SalishSeaCast/XIOS-2.git - git clone git@github.com:SalishSeaCast/XIOS-ARCH.git + $ cd $HOME/MEOPAR/ + $ git clone git@github.com:SalishSeaCast/XIOS-2.git + $ git clone git@github.com:SalishSeaCast/XIOS-ARCH.git ``salish`` ---------- -.. code-block:: bash +.. code-block:: console - cd /data/$USER/MEOPAR/ - git clone git@github.com:SalishSeaCast/XIOS-2.git - git clone git@github.com:SalishSeaCast/XIOS-ARCH.git + $ cd /data/$USER/MEOPAR/ + $ git clone git@github.com:SalishSeaCast/XIOS-2.git + $ git clone git@github.com:SalishSeaCast/XIOS-ARCH.git .. _BuildingXIOS-2: @@ -92,14 +92,14 @@ then compile and link XIOS-2. ``nibi`` -------- -.. code-block:: bash +.. code-block:: console - cd $HOME/MEOPAR/XIOS-2/arch - ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.env - ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.fcm - ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.path - cd $HOME/MEOPAR/XIOS-2 - ./make_xios --full --arch GCC_NIBI --job 8 + $ cd $HOME/MEOPAR/XIOS-2/arch + $ ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.env + $ ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.fcm + $ ln -sf ../../XIOS-ARCH/ALLIANCE/arch-GCC_NIBI.path + $ cd $HOME/MEOPAR/XIOS-2 + $ ./make_xios --full --arch GCC_NIBI --job 8 It typically takes 2 minutes or less to build XIOS-2 on ``nibi``. @@ -107,7 +107,7 @@ To build NEMO you will need an environment variable named :envvar:`XIOS_HOME` whose value is the absolute path to you :file:`XIOS-2` directory. For the ``MEOPAR`` project it is: -.. code-block:: bash +.. code-block:: console XIOS_HOME=$HOME/MEOPAR/XIOS-2 @@ -126,19 +126,19 @@ to be set automatically whenever you :command:`ssh` in. ``salish`` ---------- -.. code-block:: bash +.. code-block:: console - cd /data/$USER/MEOPAR/XIOS-2/arch - ln -sf /data/$USER/MEOPAR/XIOS-ARCH/UBC-EOAS/arch-GCC_SALISH.fcm - ln -sf /data/$USER/MEOPAR/XIOS-ARCH/UBC-EOAS/arch-GCC_SALISH.path - cd /data/$USER/MEOPAR/XIOS-2 - ./make_xios --full --arch GCC_SALISH --netcdf_lib netcdf4_seq --job 8 + $ cd /data/$USER/MEOPAR/XIOS-2/arch + $ ln -sf /data/$USER/MEOPAR/XIOS-ARCH/UBC-EOAS/arch-GCC_SALISH.fcm + $ ln -sf /data/$USER/MEOPAR/XIOS-ARCH/UBC-EOAS/arch-GCC_SALISH.path + $ cd /data/$USER/MEOPAR/XIOS-2 + $ ./make_xios --full --arch GCC_SALISH --netcdf_lib netcdf4_seq --job 8 To build NEMO you will need an environment variable named :envvar:`XIOS_HOME` whose value is the absolute path to you :file:`XIOS-2` directory. For the ``MEOPAR`` project it is: -.. code-block:: bash +.. code-block:: console XIOS_HOME=/data/$USER/MEOPAR/XIOS-2 diff --git a/zzz_archival_docs/hg_version_control.rst b/zzz_archival_docs/hg_version_control.rst index cec50aa..6048cae 100644 --- a/zzz_archival_docs/hg_version_control.rst +++ b/zzz_archival_docs/hg_version_control.rst @@ -183,24 +183,26 @@ Like your Mercurial configuration, you need to set this up on each machine that you use Mercurial on. The recommended path and name for that file is :file:`$HOME/.hgignore`. -You should create or edit your :file:`$HOME/.hgignore` file to contain:: +You should create or edit your :file:`$HOME/.hgignore` file to contain: - syntax: glob - *~ - *.pyc - *.egg-info - .ipynb_checkpoints - .DS_Store - .coverage - .cache +.. code-block:: text - syntax: regexp - (.*/)?\#[^/]*\#$ - ^docs/(.*)build/ + syntax: glob + *~ + *.pyc + *.egg-info + .ipynb_checkpoints + .DS_Store + .coverage + .cache -The :``syntax: glob`` section uses shell wildcard expansion to define file patterns to be ignored. + syntax: regexp + (.*/)?\#[^/]*\#$ + ^docs/(.*)build/ -The :``syntax: regexp`` section uses regular expressions to define ignore patterns. +The ``syntax: glob`` section uses shell wildcard expansion to define file patterns to be ignored. + +The ``syntax: regexp`` section uses regular expressions to define ignore patterns. The ``^docs/(.*)build/`` pattern ignores the products of Sphinx documentation builds in :file:`docs/` directories. Most repos have their own :file:`.hgignore` file that defines patterns to ignore for that repo in addition to those specified globally. @@ -269,9 +271,12 @@ Aborting a Merge ---------------- You may find yourself having followed Mercurial's workflow suggestions have having merged changes from upstream but then realizing that you really should have rebased. -At that point if you try to do almost anything other than commit the merge Mercurial will stop you with a message like:: +At that point if you try to do almost anything other than commit the merge Mercurial will stop you with a message like: + +.. code-block:: output + :class: no-copybutton - abort: outstanding uncommitted merges + abort: outstanding uncommitted merges You can use :command:`hg update --clean` to discard the uncommitted changes, effectively aborting the merge @@ -304,32 +309,34 @@ Commit messages can be written on the command line with the :command:`hg commit (``*``); e.g. -.. code-block:: bash +.. code-block:: console - hg commit -m"Add Salish Sea NEMO model quick-start section." + $ hg commit -m"Add Salish Sea NEMO model quick-start section." Assuming that you have the :envvar:`EDITOR` environment variable set :command:`hg commit` without the ``-m`` option will open your editor for you to write your commit message and the files to be committed will be shown in the editor. Using your editor for commit message also makes it easy to write multi-line commit messages. -Here are recommendations for commit message style:: +Here are recommendations for commit message style: - Short (70 chars or less) summary sentence. +.. code-block:: text - More detailed explanatory text, if necessary. Wrap it to about 72 - characters or so. The blank line separating the summary from the body - is critical (unless you omit the body entirely). + Short (70 chars or less) summary sentence. - Write your commit message in the imperative: "Fix bug" and not "Fixed bug" - or "Fixes bug." + More detailed explanatory text, if necessary. Wrap it to about 72 + characters or so. The blank line separating the summary from the body + is critical (unless you omit the body entirely). - Further paragraphs come after blank lines. + Write your commit message in the imperative: "Fix bug" and not "Fixed bug" + or "Fixes bug." - - Bullet points are okay, too + Further paragraphs come after blank lines. - - Typically a hyphen or asterisk is used for the bullet, followed by a - single space, with blank lines in between + - Bullet points are okay, too - - Use a hanging indent + - Typically a hyphen or asterisk is used for the bullet, followed by a + single space, with blank lines in between + + - Use a hanging indent .. _WorkAroundForCloningTimeout: @@ -344,11 +351,11 @@ For example, for the ``NEMO-3.6-code`` repo, the process to do that is: -.. code-block:: bash +.. code-block:: console - hg clone --rev 1 ssh://hg@bitbucket.org/salishsea/nemo-3.6-code NEMO-3.6-code - cd NEMO-3.6-code - hg pull --update + $ hg clone --rev 1 ssh://hg@bitbucket.org/salishsea/nemo-3.6-code NEMO-3.6-code + $ cd NEMO-3.6-code + $ hg pull --update We think that the root cause of the timeout during cloning is that after the initial repo bundle is downloaded from Bitbucket the local processing of the bundle is so slow on the $PROJECT file systems of some HPC clusters that Bitbucket assumes that the network connection being used for the cloning operation has failed. Clone just the first changeset avoids the bundle download operation.