Skip to content

Add sphinx-copybutton for enhanced documentation interactivity #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
douglatornell merged 7 commits into from
Feb 25, 2026
Merged

Add sphinx-copybutton for enhanced documentation interactivity #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2e278e1
Add `sphinx-copybutton` to docs & dev dependencies
douglatornell Feb 24, 2026
d495143
Add `sphinx_copybutton` to Sphinx configuration
douglatornell Feb 24, 2026
8959b2e
Configure `sphinx_copybutton` extension in Sphinx
douglatornell Feb 24, 2026
807ec58
Add PowerShell prompt to copybutton prompt regex
douglatornell Feb 24, 2026
b55aa6b
Start to use `code-block:: console` for commands
douglatornell Feb 24, 2026
9bad584
Finish chg to use `code-block:: console` for commands
douglatornell Feb 25, 2026
11abb25
Use `.. code-block:: output` for output formatting
douglatornell Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions alliance-computing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -152,15 +152,15 @@ 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

Exit your session on ``nibi`` with :command:`exit`,
then :command:`ssh` in again,
and confirm that :envvar:`PROJECT` is set correctly with:

.. code-block:: bash
.. code-block:: console

$ echo $PROJECT

Expand All @@ -174,23 +174,23 @@ 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

#. Set the permissions in your :file:`$PROJECT/$USER/` directory so that other members 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 $PROJECT/$USER
$ chmod g+rwxs $PROJECT/$USER

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
Expand All @@ -203,15 +203,15 @@ 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

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
Expand All @@ -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
Expand Down
98 changes: 55 additions & 43 deletions analysis_repo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -115,22 +115,25 @@ 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

Or,
for laptop setup do:

.. code-block:: bash
.. code-block:: console

$ cd $HOME/MOAD
$ git clone git@github.com:SalishSeaCast/analysis-casey.git
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -230,7 +239,7 @@ Populate Your Analysis Repository

#. Deactivate your ``cookiecutter`` environment with:

.. code-block:: bash
.. code-block:: console

(cookiecutter)$ conda deactivate

Expand All @@ -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/
Expand All @@ -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/
Expand All @@ -275,15 +284,15 @@ 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

Or,
for laptop setup do:

.. code-block:: bash
.. code-block:: console

$ cd $HOME/MOAD/analysis-casey/notebooks/
$ conda env create -f environment.yaml
Expand All @@ -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`.
Expand All @@ -330,15 +342,15 @@ 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

Or,
for laptop setup do:

.. code-block:: bash
.. code-block:: console

$ cd $HOME/MOAD/
$ git clone git@github.com:SalishSeaCast/tools.git
Expand All @@ -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
Expand Down
Loading