diff --git a/config/nowcast.yaml b/config/nowcast.yaml index ec87440b..0d6a0f7d 100644 --- a/config/nowcast.yaml +++ b/config/nowcast.yaml @@ -1242,7 +1242,7 @@ message registry: no after_worker function: ERROR - after_worker function not found in next_workers module # Module from which to load :py:func:`after_` functions - # that provide lists of workers to launch when :kbd:`worker_name` finishes. + # that provide lists of workers to launch when ``worker_name`` finishes. # Use fully qualified, dotted notation. next workers module: nowcast.next_workers diff --git a/config/ww3_hindcast.yaml b/config/ww3_hindcast.yaml index 9b7d5658..4520cc09 100644 --- a/config/ww3_hindcast.yaml +++ b/config/ww3_hindcast.yaml @@ -212,7 +212,7 @@ message registry: no after_worker function: ERROR - after_worker function not found in next_workers module # Module from which to load :py:func:`after_` functions - # that provide lists of workers to launch when :kbd:`worker_name` finishes. + # that provide lists of workers to launch when ``worker_name`` finishes. # Use fully qualified, dotted notation. next workers module: nowcast.next_workers diff --git a/docs/conf.py b/docs/conf.py index 2977724f..93c9a739 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,15 +86,12 @@ "moad_tools.places", "mpl_toolkits.basemap", "nemo_cmd", - "nemo_nowcast.fileutils", - "nemo_nowcast.workers", - "nemo_nowcast.workers.clear_checklist", - "nemo_nowcast.workers.rotate_logs", "netCDF4", "OPPTools", "pandas", "paramiko", "PyPDF2", + "reshapr", "salishsea_cmd", "salishsea_cmd.api", "salishsea_tools", diff --git a/docs/deployment/index.rst b/docs/deployment/index.rst index f803e0f5..7c791083 100644 --- a/docs/deployment/index.rst +++ b/docs/deployment/index.rst @@ -30,42 +30,42 @@ The production deployment uses 2 systems: #. The :py:mod:`nemo_nowcast.message_broker`, :py:mod:`nemo_nowcast.manager`, :py:mod:`nemo_nowcast.log_aggregator`, - most of the pre- and post-processing workers run on the :ref:`SalishSeaModelResultsServer`, :kbd:`skookum`, where the deployment is in the :file:`/SalishSeaCast/` directory tree. + most of the pre- and post-processing workers run on the :ref:`SalishSeaModelResultsServer`, :`m``, where the deployment is in the :file:`/SalishSeaCast/` directory tree. #. The daily - :kbd:`forecast2` + ``forecast2`` (preliminary forecast), - :kbd:`nowcast`, - :kbd:`forecast`, - and :kbd:`nowcast-green` NEMO-3.6 model runs are computed on a cluster of virtual machines provided by `Ocean Networks Canada`_ on the Compute Canada `arbutus.cloud`_ cluster. - The shared storage for those VMs is provided by an NFS-mounted volume of ::kbd:`arbutus.cloud` `Ceph object storage`_. + ``nowcast``, + ``forecast``, + and ``nowcast-green`` NEMO-3.6 model runs are computed on a cluster of virtual machines provided by `Ocean Networks Canada`_ on the Compute Canada `arbutus.cloud`_ cluster. + The shared storage for those VMs is provided by an NFS-mounted volume of ``arbutus.cloud`` `Ceph object storage`_. The nowcast deployment is in the :file:`/nemoShare/MEOPAR/nowcast-sys/` directory tree. In April 2017, - daily :kbd:`wwatch3-nowcast`, - daily :kbd:`wwatch3-forecast`, - and :kbd:`wwatch3-forecast2` + daily ``wwatch3-nowcast``, + daily ``wwatch3-forecast``, + and ``wwatch3-forecast2`` (preliminary wave forecast) - WaveWatch III® v5.16 wave model runs for the Strait of Georgia and Juan de Fuca Strait were added to the computations on :kbd:`arbutus.cloud`. - The :kbd:`wwatch3-nowcast` and :kbd:`wwatch3-forecast` runs are executed in sequence after the daily :kbd:`nowcast-green` NEMO-3.6 runs. - The :kbd:`wwatch3-forecast2` runs are executed after the daily :kbd:`forecast2` NEMO-3.6 runs. + WaveWatch III® v5.16 wave model runs for the Strait of Georgia and Juan de Fuca Strait were added to the computations on ``arbutus.cloud``. + The ``wwatch3-nowcast`` and ``wwatch3-forecast`` runs are executed in sequence after the daily ``nowcast-green`` NEMO-3.6 runs. + The ``wwatch3-forecast2`` runs are executed after the daily ``forecast2`` NEMO-3.6 runs. In January 2018, - daily :kbd:`fvcom-nowcast` - and :kbd:`fvcom-forecast` FVCOM v4.1-beta model runs for Vancouver Harbour and the Lower Fraser River were added to the computations on the :kbd:`arbutus.cloud`. - They are executed in sequence after the daily :kbd:`nowcast` NEMO-3.6 runs. + daily ``fvcom-nowcast`` + and ``fvcom-forecast`` FVCOM v4.1-beta model runs for Vancouver Harbour and the Lower Fraser River were added to the computations on the ``arbutus.cloud``. + They are executed in sequence after the daily ``nowcast`` NEMO-3.6 runs. In January 2019, the resolution of the Vancouver Harbour and Lower Fraser River FVCOM v4.1-beta model was increased. - Those runs are designated :kbd:`fvcom-nowcast-x2` and :kbd:`fvcom-forecast-x2`. + Those runs are designated ``fvcom-nowcast-x2`` and ``fvcom-forecast-x2``. In March 2019, an even higher resolution Vancouver Harbour and Lower Fraser River model configuration was added to the system, - running daily nowcast runs as :kbd:`fvcom-nowcast-r12`. + running daily nowcast runs as ``fvcom-nowcast-r12``. .. _Ocean Networks Canada: https://www.oceannetworks.ca/ .. _arbutus.cloud: https://docs.alliancecan.ca/wiki/Cloud_resources#Arbutus_cloud .. _Ceph object storage: https://en.wikipedia.org/wiki/Ceph_(software) -These sections describe the setup of the nowcast system on :kbd:`skookum` and :kbd:`arbutus.cloud`, +These sections describe the setup of the nowcast system on ``skookum`` and ``arbutus.cloud``, and their operation. .. toctree:: @@ -75,9 +75,9 @@ and their operation. arbutus_cloud operations -In May 2018 production runs of a :kbd:`nowcast-green` configuration with AGRIF sub-grids for Baynes Sound and Haro Strait were added to the system. -Those runs are executed on a reserved chassis on :kbd:`orcinus`. -The setup on :kbd:`orcinus`, +In May 2018 production runs of a ``nowcast-green`` configuration with AGRIF sub-grids for Baynes Sound and Haro Strait were added to the system. +Those runs are executed on a reserved chassis on ``orcinus``. +The setup on ``orcinus``, as well are the sub-grid initialization preparation with the NEMO-AGRIF nesting tools are described in: .. toctree:: @@ -85,10 +85,10 @@ as well are the sub-grid initialization preparation with the NEMO-AGRIF nesting orcinus -In February 2019 we got access to the UBC EOAS :kbd:`optimum` cluster. +In February 2019 we got access to the UBC EOAS ``optimum`` cluster. We use it primarily for long hindcast runs, but also some research runs. -The setup on :kbd:`optimum` is described in: +The setup on ``optimum`` is described in: .. toctree:: :maxdepth: 2 @@ -100,8 +100,8 @@ See also the `#optimum-cluster`_ Slack channel. .. _#optimum-cluster: https://salishseacast.slack.com/?redir=%2Farchives%2FC011S7BCWGK With the update of the production to run the V21-11 model version in January 2024, -we decided to end the daily :kbd:`nowcast-dev` development model runs on :kbd:`salish`. -Development is now generally done in research runs on :kbd:`graham`. -:kbd:`salish` is now mostly used for analysis tasks, post-processing of NEMO model results files +we decided to end the daily ``nowcast-dev`` development model runs on ``salish``. +Development is now generally done in research runs on ``graham``. +``salish`` is now mostly used for analysis tasks, post-processing of NEMO model results files to produce day-average and month-average dataset files, and Lagrangian particle tracking analysis with :program:`ariane` and :program:`OceanParcels`. diff --git a/docs/deployment/operations.rst b/docs/deployment/operations.rst index 60cdfe04..c80f6c23 100644 --- a/docs/deployment/operations.rst +++ b/docs/deployment/operations.rst @@ -76,30 +76,30 @@ Start it with: .. _supervisorctl: http://supervisord.org/running.html#running-supervisorctl See the `supervisorctl`_ docs, -or use the :kbd:`help` command within :command:`supervisorctl` to get information on the available commands. +or use the ``help`` command within :command:`supervisorctl` to get information on the available commands. A few that are useful: -* :kbd:`avail` to get a list of the processes that :command:`supervisord` is configured to manage -* :kbd:`status` to see their status -* :kbd:`stop` to stop a process; - e.g. :kbd:`stop manager` -* :kbd:`start` to start a stopped process; - e.g. :kbd:`start manager` -* :kbd:`restart` to stop and restart a process; - e.g. :kbd:`restart manager` -* :kbd:`signal hup` to send a :kbd:`HUP` signal to a process, +* ``avail`` to get a list of the processes that :command:`supervisord` is configured to manage +* ``status`` to see their status +* ``stop`` to stop a process; + e.g. ``stop manager`` +* ``start`` to start a stopped process; + e.g. ``start manager`` +* ``restart`` to stop and restart a process; + e.g. ``restart manager`` +* ``signal hup`` to send a ``HUP`` signal to a process, which will cause it to reload its configuration from the :envvar:`NOWCAST_YAML` file that the process was started with; - e.g. :kbd:`signal hup manager`. + e.g. ``signal hup manager``. This is the way to communicate nowcast system configuration changes to the long-running processes. -* :kbd:`shutdown` to stop all of the processes and shutdown :command:`supervisord` +* ``shutdown`` to stop all of the processes and shutdown :command:`supervisord` -Use :kbd:`quit` or :kbd:`exit` to exit from :command:`supervisorctl`. +Use ``quit`` or ``exit`` to exit from :command:`supervisorctl`. `sr_subscribe`_ is the command-line interface for interacting with the `sarracenia client`_ that maintains mirrors of the HRDPS forecast files and rivers hydrometric files from the `ECCC MSC datamart service`_. .. _sr_subscribe: https://github.com/MetPX/sarracenia/blob/v2_dev/doc/sr_subscribe.1.rst -:command:`sr_subscribe` is run in :kbd:`foreground` mode instead of daemonized so that it can be managed by ::command:`supervisord`. +:command:`sr_subscribe` is run in ``foreground`` mode instead of daemonized so that it can be managed by ::command:`supervisord`. Use :command:`supervisorctl` to view the :command:`sr_subscribe` log files:\ .. code-block:: bash @@ -116,8 +116,8 @@ or Use :command:`tail -f` to follow the logs to view updates as they occur. -Automatic Deployment of Changes to :kbd:`salishsea-site` App -============================================================ +Automatic Deployment of Changes to ``salishsea-site`` App +========================================================= A `GitHub Actions workflow`_ causes changes to be pulled and updated to :file:`/SalishSeaCast/salishsea-site/` and the app to be restarted via :command:`supervisorctl` whenever changes are pushed to the repo on GitHub. diff --git a/docs/deployment/optimum.rst b/docs/deployment/optimum.rst index 08320433..85b51f86 100644 --- a/docs/deployment/optimum.rst +++ b/docs/deployment/optimum.rst @@ -18,11 +18,11 @@ .. _OptimumDeployment: -******************************************* -:kbd:`optimum` Deployment for Hindcast Runs -******************************************* +**************************************** +``optimum`` Deployment for Hindcast Runs +**************************************** -Doug maintains the production deployment on :kbd:`optimum` in the group :kbd:`sallen` directory trees. +Doug maintains the production deployment on ``optimum`` in the group ``sallen`` directory trees. That means that, for the purposes of these docs, the value of :envvar:`HOME` is :file:`/home/sallen/dlatorne`. @@ -36,7 +36,7 @@ Add these environment variable definitions to :file:`$HOME/.bash_profile`:: export FORCING=/data/sallen/shared export PROJECT=/home/sallen/dlatorne -:kbd:`optimum` provides automatically defined environment variables for: +``optimum`` provides automatically defined environment variables for: :envvar:`ARCHIVEDIR` for storing semi-permanent input and results. (no backup) @@ -51,14 +51,14 @@ Add these environment variable definitions to :file:`$HOME/.bash_profile`:: Module Loads ============ -The default module loads to use on :kbd:`optimum` are:: +The default module loads to use on ``optimum`` are:: module load OpenMPI/2.1.6/GCC/SYSTEM module load GIT/2/03.03 Loading of those modules is included in :file:`$HOME/.bashrc`. -There is a :kbd:`Miniconda/3` module available for building Python Conda environments. +There is a ``Miniconda/3`` module available for building Python Conda environments. Conda environments created with that module loaded are stored in :file:`$HOME/.conda/envs/`. There is something funky about :program:`REBUILD_NEMO` and the way it uses netCDF that requires a different collection of modules in order to avoid a run-time error about netCDF4 operations on netCDF3 files @@ -123,7 +123,7 @@ Clone the following repos into :file:`$PROJECT/SalishSeaCast/hindcast-sys/`: Build XIOS-2 ============ -Symlink the XIOS-2 build configuration files for :kbd:`optimum` from the :file:`XIOS-ARCH` repo clone into the :file:`XIOS-2/arch/` directory: +Symlink the XIOS-2 build configuration files for ``optimum`` from the :file:`XIOS-ARCH` repo clone into the :file:`XIOS-2/arch/` directory: .. code-block:: bash @@ -135,10 +135,10 @@ Symlink the XIOS-2 build configuration files for :kbd:`optimum` from the :file:` Despite many attempts with various combinations of compilers, OpenMPI library versions, and netCDF library versions, -the only way found to successfully build XIOS-2 is with the :kbd:`OpenMPI/2.1.6/GCC/SYSTEM` module. -That forces us to use the SVN :kbd:`r1066` checkout version of XIOS-2. -That version is pointed to by both the :kbd:`XIOS-2r1066` and the :kbd:`PROD-hindcast_201905-v3` -(and later :kbd:`PROD-hindcast_*`) +the only way found to successfully build XIOS-2 is with the ``OpenMPI/2.1.6/GCC/SYSTEM`` module. +That forces us to use the SVN ``r1066`` checkout version of XIOS-2. +That version is pointed to by both the ``XIOS-2r1066`` and the ``PROD-hindcast_201905-v3`` +(and later ``PROD-hindcast_*``) Git tags, so create a branch to checkout the repo at one of those tags: @@ -153,7 +153,7 @@ and build XIOS-2 with: $ cd $PROJECT/SalishSeaCast/hindcast-sys/XIOS-2/ $ ./make_xios --arch GCC_OPTIMUM --netcdf_lib netcdf4_seq --job 8 -:kbd:`--netcdf_lib netcdf4_seq` is necessary because the :kbd:`OpenMPI/2.1.6/GCC/SYSTEM` NetCDF libraries are not built for parallel output. +``--netcdf_lib netcdf4_seq`` is necessary because the ``OpenMPI/2.1.6/GCC/SYSTEM`` NetCDF libraries are not built for parallel output. To clear away all artifacts of a previous build of XIOS-2 use: @@ -209,7 +209,7 @@ Build it with: Install Python Packages ======================= -Load the :kbd:`Miniconda/3` module and create a Conda environment: +Load the ``Miniconda/3`` module and create a Conda environment: .. code-block:: bash diff --git a/docs/deployment/orcinus.rst b/docs/deployment/orcinus.rst index 5449d3f5..d79c7614 100644 --- a/docs/deployment/orcinus.rst +++ b/docs/deployment/orcinus.rst @@ -18,9 +18,9 @@ .. _OrcinusDeployment: -******************************************************* -:kbd:`orcinus` Deployment for :kbd:`nowcast-agrif` Runs -******************************************************* +************************************************* +``orcinus`` Deployment for ``nowcast-agrif`` Runs +************************************************* Create Directory Trees ====================== @@ -65,7 +65,7 @@ Clone the following repos into :file:`/home/dlatorne/nowcast-agrif-sys/`: Build XIOS-2 ============ -Symlink the XIOS-2 build configuration files for :kbd:`orcinus` from the :file:`XIOS-ARCH` repo clone into the :file:`XIOS-2/arch/` directory: +Symlink the XIOS-2 build configuration files for ``orcinus`` from the :file:`XIOS-ARCH` repo clone into the :file:`XIOS-2/arch/` directory: .. code-block:: bash @@ -80,7 +80,7 @@ and build XIOS-2 with: $ cd /home/dlatorne/nowcast-agrif-sys/XIOS-2 $ ./make_xios --arch X64_ORCINUS --netcdf_lib netcdf4_seq --job 8 -:kbd:`--netcdf_lib netcdf4_seq` is necessary because AGRIF does not support parallel NetCDF output. +``--netcdf_lib netcdf4_seq`` is necessary because AGRIF does not support parallel NetCDF output. To clear away all artifacts of a previous build of XIOS-2 use: @@ -157,7 +157,7 @@ Sub-grid Initialization Preparation with Nesting Tools Build Nesting Tools ------------------- -Clone Michael Dunphies' debugged version of the nesting tools for AGRIF from :file:`NEMO-3.6-code/NEMOGCM/TOOLS/NESTING/` on to :kbd:`salish`: +Clone Michael Dunphies' debugged version of the nesting tools for AGRIF from :file:`NEMO-3.6-code/NEMOGCM/TOOLS/NESTING/` on to ``salish``: .. code-block:: bash @@ -197,7 +197,7 @@ Coordinates For the Baynes Sound sub-grid, use :program:`agrif_create_coordinates.exe` to create the sub-grid coordinates file from the full domain coordinates (path provided in the :file:`namelist.nesting.BaynesSound` file), -and add it to the :kbd:`grid` repo: +and add it to the ``grid`` repo: .. code-block:: bash @@ -231,7 +231,7 @@ Bathymetry .. note:: Need to understand the details of how sub-grid bathymetries are generated. - They appear to be based on :file:`/home/mdunphy/MEOPAR/WORK/Bathy-201702/BC3/BC3_For_Nesting_Tools.nc` and a :kbd:`bathymetry` namelist like: + They appear to be based on :file:`/home/mdunphy/MEOPAR/WORK/Bathy-201702/BC3/BC3_For_Nesting_Tools.nc` and a ``bathymetry`` namelist like: .. code-block:: bash @@ -260,7 +260,7 @@ we can construct an acceptable rivers biological tracers forcing file for the Ba This will have to be revisited if/when we change the Puntledge River to use real-time discharges values from a gauge. Calculate the :file:`rivers-climatology/bio/subgrids/BaynesSound/bio/rivers_bio_tracers_mean.nc`, -and add it to the :kbd:`rivers-climatology` repo: +and add it to the ``rivers-climatology`` repo: .. code-block:: bash @@ -281,7 +281,7 @@ The commands in this section are for generation of sub-grid physics restart file For the Baynes Sound sub-grid, use :program:`agrif_create_restart.exe` to create the sub-grid physics restart file from the full domain physics restart file, -and upload both files to the appropriate run results directory on :kbd:`orcinus`: +and upload both files to the appropriate run results directory on :`s``: .. code-block:: bash @@ -316,7 +316,7 @@ The commands in this section are for generation of sub-grid tracer restart files For the Baynes Sound sub-grid, use :program:`agrif_create_restart_trc.exe` to create the sub-grid tracer restart file from the full domain tracer restart file, -and upload both files to the appropriate run results directory on :kbd:`orcinus`: +and upload both files to the appropriate run results directory on :`s``: .. code-block:: bash @@ -339,10 +339,10 @@ start by using :program:`agrif_create_restart_trc.exe` to create the sub-grid tr $ /data/dlatorne/MEOPAR/NestingTools/NEMOGCM/TOOLS/NESTING/agrif_create_restart_trc.exe \ namelist.nesting.HaroStrait -For some reason :program:`agrif_create_restart_trc.exe` fails to store the variable :kbd:`TRBTRA` -(the Fraser River tracer :kbd:`B` field, and the final variable) +For some reason :program:`agrif_create_restart_trc.exe` fails to store the variable ``TRBTRA`` +(the Fraser River tracer ``B`` field, and the final variable) in the file it produces. -To deal with that we duplicate the :kbd:`TRNTRA` field values as :kbd:`TRBTRA` and append that variable to the file: +To deal with that we duplicate the ``TRNTRA`` field values as ``TRBTRA`` and append that variable to the file: .. code-block:: bash @@ -351,7 +351,7 @@ To deal with that we duplicate the :kbd:`TRNTRA` field values as :kbd:`TRBTRA` a $ ncrename -O -v TRNTRA,TRBTRA TRNTRA.nc TRBTRA.nc $ ncks -4 -A TRBTRA.nc 1_SalishSea_02935440_restart_trc.nc -and upload the file to the appropriate run results directory on :kbd:`orcinus`: +and upload the file to the appropriate run results directory on :`s``: .. code-block:: bash diff --git a/docs/deployment/skookum.rst b/docs/deployment/skookum.rst index 7107c547..21128d97 100644 --- a/docs/deployment/skookum.rst +++ b/docs/deployment/skookum.rst @@ -18,9 +18,9 @@ .. _SkookumDeployment: -************************ -:kbd:`skookum`Deployment -************************ +********************** +``skookum`` Deployment +********************** Git Repositories ================ @@ -60,7 +60,7 @@ The Python packages that the system depends on are installed in conda environmen .. _Mambaforge-pypy3: https://github.com/conda-forge/miniforge -For the :kbd:`SalishSeaCast` automation system: +For the ``SalishSeaCast`` automation system: .. code-block:: bash @@ -228,17 +228,17 @@ On the hosts where the nowcast system NEMO runs will be executed create a The hosts and their :file:`runs` directories presently in use are: -* :kbd:`arbutus.cloud` +* ``arbutus.cloud`` See :ref:`ArbutusCloudNEMORunsDirectory` -* :kbd:`orcinus` +* ``orcinus`` :file:`/home/sallen/MEOPAR/nowcast/` ECCC MSC Datamart Mirror Directories ==================================== -Create directories on :kbd:`skookum` for storage of the HRDPS forecast files and +Create directories on ``skookum`` for storage of the HRDPS forecast files and rivers hydrometric files maintained by the `sarracenia client`_: .. code-block:: bash @@ -250,7 +250,7 @@ rivers hydrometric files maintained by the `sarracenia client`_: Logging Directories =================== -Create directories on :kbd:`skookum` for storage of the nowcast system and +Create directories on ``skookum`` for storage of the nowcast system and `salishsea-site web app`_ log files: .. code-block:: bash @@ -338,15 +338,15 @@ The :py:mod:`~nowcast.workers.make_averaged_dataset` worker is launched: That means that there are often concurrent instances of the worker. Instead of letting each worker instance spin up its own *ad hoc* dask cluster, -we use a persistent dask cluster on :kbd:`salish` that the worker dispatches tasks to. +we use a persistent dask cluster on ``salish`` that the worker dispatches tasks to. -Create a ``tmux`` session on :kbd:`salish` for the dask cluster: +Create a :program:`tmux` session on ``salish`` for the dask cluster: .. code-block:: bash $ tmux new -s make_averaged_dataset -In the first ``tmux`` terminal, +In the first :program:`tmux` terminal, activate the :file:`/SalishSeaCast/nowcast-env` environment, and launch the :command:`dask-scheduler` with its serving port on 4386, and its dashboard port on 4387: @@ -354,26 +354,95 @@ and its dashboard port on 4387: .. code-block:: bash $ conda activate /SalishSeaCast/nowcast-env - (/SalishSeaCast/nowcast-env)$ dask-scheduler --port 4386 --dashboard-address :4387 + (/SalishSeaCast/nowcast-env)$ dask scheduler --port 4386 --dashboard-address :4387 -Use :kbd:`Control-b ,` to rename the ``tmux`` terminal to ``dask-scheduler``. +Use :kbd:`Control-b ,` to rename the :program:`tmux` terminal to ``dask-scheduler``. -Start a second ``tmux`` terminal with :kbd:`Control-b c`, +Start a second :program:`tmux` terminal with :kbd:`Control-b c`, activate the :file:`/SalishSeaCast/nowcast-env` environment, -and launch the 4 :command:`dask-worker` processes with there properties: +and launch the 4 :command:`dask worker` processes with these properties: -* 4 threads per worker -* memory limit per worker process computed automatically -* worker files stored on the :file:`/dev/shm` shared memory file system +* 1 thread per worker +* 64G memory limit per worker +* worker files stored on the :file:`/tmp/` file system * workers restart every 3600 seconds with 60 second random staggering of their restart times * workers communicate with the scheduler on port 4386 .. code-block:: bash $ conda activate /SalishSeaCast/nowcast-env - (/SalishSeaCast/nowcast-env)$ dask-worker --nworkers=4 --nthreads=4 --memory-limit auto \ - --local-directory /dev/shm \ - --lifetime 3600 --lifetime-stagger 60 --lifetime-restart \ - localhost:4386 + (/SalishSeaCast/nowcast-env)$ dask worker --nworkers=4 --nthreads=1 --memory-limit 64G \ + --local-directory /tmp \ + --lifetime 3600 --lifetime-stagger 60 --lifetime-restart \ + localhost:4386 -Use :kbd:`Control-b ,` to rename the ``tmux`` terminal to ``dask-workers``. +Use :kbd:`Control-b ,` to rename the :program:`tmux` terminal to ``dask-workers``. + + + +``ssh`` Keys and Configuration +============================== + +Generate a passphrase-less RSA key pair to use for connections to most remote hosts: + +.. code-block:: bash + + $ ssh-keygen -t rsa -f $HOME/.ssh/SalishSeaNEMO-nowcast_id_rsa -C SalishSeaNEMO-nowcast + +Use :command:`ssh-copy-id` to install the public key on ``arbutus``, +``optimum``, +and ``orcinus``; +e.g. + +.. code-block:: bash + + $ ssh-copy-id -i $HOME/.ssh/SalishSeaNEMO-nowcast_id_rsa arbutus.cloud + +Generate a passphrase-less ED25519 key pair to use for connections to the ``graham`` HPC cluster: + +.. code-block:: bash + + ssh-keygen -t ed25519 -f $HOME/.ssh/SalishSeaCast_robot.graham_ed25519 -C "SalishSeaCast robot.graham" + +Edit the public key to prefix it with the constraint predicates necessary for automation in the +context of multuifactor authentication on the ``graham`` cluster. +The constraint predicates are: + +.. code-block:: text + + restrict,from="142.103.36.*",command="/cvmfs/soft.computecanada.ca/custom/bin/computecanada/allowed_commands/transfer_commands.sh" + +Use https://ccdb.computecanada.ca/ssh_authorized_keys to install the public key for ``graham`` via +the Alliance CCDB. + +Add the following stanzas to :file:`$HOME/.ssh/config` on ``skookum``: + +.. code-block:: text + + Host arbutus.cloud-nowcast + HostName + User ubuntu + IdentityFile ~/.ssh/SalishSeaNEMO-nowcast_id_rsa + ForwardAgent no + + Host robot.graham + HostName robot.graham.alliancecan.ca + User + IdentityFile ~/.ssh/SalishSeaCast_robot.graham_ed25519 + ForwardAgent no + + Host optimum-hindcast + HostName optimum.eos.ubc.ca + User + HostKeyAlgorithms=+ssh-rsa + PubkeyAcceptedKeyTypes=+ssh-rsa + IdentityFile ~/.ssh/SalishSeaNEMO-nowcast_id_rsa + ForwardAgent no + + Host orcinus-nowcast-agrif + HostName orcinus.westgrid.ca + User + HostKeyAlgorithms=+ssh-rsa + PubkeyAcceptedKeyTypes=+ssh-rsa + IdentityFile ~/.ssh/SalishSeaNEMO-nowcast_id_rsa + ForwardAgent no diff --git a/docs/figures/create_fig_module.rst b/docs/figures/create_fig_module.rst index 46593328..5cc2cbf1 100644 --- a/docs/figures/create_fig_module.rst +++ b/docs/figures/create_fig_module.rst @@ -291,7 +291,7 @@ and then we'll look at each section in detail. .. note:: Line numbers beside the code fragments in this section would be a definite improvement. - Unfortunately they are badly misaligned in the :kbd:`sphinx_rtd_theme` presently deployed on readthedocs.org (v0.1.7). + Unfortunately they are badly misaligned in the ``sphinx_rtd_theme`` presently deployed on readthedocs.org (v0.1.7). That bug is fixed in v0.1.9, broken again somewhere between that version and v0.2.4, and fixed again in v0.2.5b1. @@ -406,7 +406,7 @@ the import must be present in every figure module. :py:mod:`nowcast.figures.website_theme` provides the definition of colours and fonts that figure modules must use in order to ensure consistency from one to the next, -and with the :kbd:`salishsea.eos.ubc.ca` site NEMO results section styling. +and with the ``salishsea.eos.ubc.ca`` site NEMO results section styling. See :ref:`nowcast.figures.website_theme` for more details about the :py:mod:`~nowcast.figures.website_theme` module. @@ -493,16 +493,16 @@ The function signature should use model results dataset objects rather than file names so that the datasets are loaded once by the :py:mod:`nowcast.workers.make_plots` worker and references to them passed into the figure creation functions. -The signature ends with the default-values keyword arguments :kbd:`figsize` and :kbd:`theme`. +The signature ends with the default-values keyword arguments ``figsize`` and ``theme``. -The :kbd:`figsize` 2-tuple give the width and height of the figure, +The ``figsize`` 2-tuple give the width and height of the figure, but more importantly its aspect ratio. Choose values that are appropriate to the information presented in the figure. If you don't have a good reason to choose something else, -use :kbd:`figsize=(16, 9)` because that matches the aspect ration of wide displays that most people use to view web sites +use ``figsize=(16, 9)`` because that matches the aspect ration of wide displays that most people use to view web sites (even phones in landscape orientation). -The :kbd:`theme` should be defaulted to :py:mod:`nowcast.figures.website_theme`, a module that provides colours and font specifications that fit with the `salishsea site`_ colour scheme and provide consistency among the figures. +``theme`` should be defaulted to :py:mod:`nowcast.figures.website_theme`, a module that provides colours and font specifications that fit with the `salishsea site`_ colour scheme and provide consistency among the figures. .. _salishsea site: https://salishsea.eos.ubc.ca @@ -549,7 +549,7 @@ Those are written using `Sphinx Info Field List markup`_ so that they render nic .. _Sphinx Info Field List markup: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists Simple, -1-word type information can be included in the :kbd:`:param ...:` role, +1-word type information can be included in the ``:param ...:`` role, for example: .. code-block:: restructuredtext @@ -557,7 +557,7 @@ for example: :param boolean depth_integrated: Integrate the tracer over the water column depth when :py:obj:`True`. -More complicated type information should go in a separate :kbd:`:type ...:` role like: +More complicated type information should go in a separate ``:type ...:`` role like: .. code-block:: restructuredtext @@ -588,9 +588,9 @@ The function code does 4 things: * a tuple of :py:class:`matplotlib.axes.Axes` objects, one for each axes in the figure - The :py:func:`_prep_fig_axes` function accept arguments named :kbd:`figsize` and :kbd:`theme`. - :kbd:`figsize` provides the size and shape of the figure area. - :kbd:`theme` provides the :py:mod:`nowcast.figures.website_theme` :ref:`WebsiteTheme` module which defines things like the figure and axes background colours. + The :py:func:`_prep_fig_axes` function accept arguments named ``figsize`` and ``theme``. + ``figsize`` provides the size and shape of the figure area. + ``theme`` provides the :py:mod:`nowcast.figures.website_theme` :ref:`WebsiteTheme` module which defines things like the figure and axes background colours. The tuple of axes objects returned by :py:func:`_prep_fig_axes` should be given meaningful names as shown above rather than: @@ -685,9 +685,8 @@ Please see :ref:`LibraryCodeSalishSeaToolsPlaces` for more details. :py:func:`_prep_fig_axes` Function ================================== -The :py:func:`_prep_fig_axes` function accepts arguments named :kbd:`figsize` and :kbd:`theme`. -:kbd:`figsize` provides the size and shape of the figure area. -:kbd:`theme` provides the :py:mod:`nowcast.figures.website_theme` :ref:`WebsiteTheme` module which defines things like the figure and axes background colours. +The :py:func:`_prep_fig_axes` function accepts arguments named ``figsize`` and ``theme``. +``figsize`` provides the size and shape of the figure ``theme`` provides the :py:mod:`nowcast.figures.website_theme` :ref:`WebsiteTheme` module which defines things like the figure and axes background colours. .. code-block:: python @@ -732,16 +731,16 @@ one for each :py:obj:`matplotlib.axes.Axes` object returned by :py:func:`_prep_f Those functions generally accept: * a :py:obj:`matplotlib.axes.Axes` object as their 1st argument, - called :kbd:`ax` by convention + called ``ax`` by convention * the :py:obj:`~types.SimpleNamespace` object that was returned by the :py:func:`_prep_plot_data` function, - called :kbd:`plot_data` by convention + called ``plot_data`` by convention * the :py:mod:`nowcast.figures.website_theme` module as their last argument, - called :kbd:`theme` by convention + ``theme`` by convention They may accept other arguments as necessary. The job of the :py:func:`_plot_*` functions is to act on the :py:obj:`matplotlib.axes.Axes` object -(:kbd:`ax`) +(``ax``) so they may or may not return anything. @@ -787,7 +786,7 @@ It returns the :py:obj:`cbar` colour bar object for a separate :py:func:`_thalwe fontproperties=theme.FONTS['axis']) theme.set_axis_colors(ax) -This function shows how text colours and fonts are obtained from :kbd:`theme`. +This function shows how text colours and fonts are obtained from ``theme``. It finishes with a call to the :py:func:`theme.set_axis_colors` convenience function to set the colours of axis labels, ticks, and spines so that they are consistent with the web site theme. @@ -804,7 +803,7 @@ The code format the colour bar labels is in separate :py:func:`_cbar_labels` fun fontproperties=theme.FONTS['axis'], color=theme.COLOURS['text']['axis']) -The colour of the tick labels on the colorbar is set by calling the :py:meth:`axes.tick_params` method on the axes object with a colour provided by :kbd:`theme`. +The colour of the tick labels on the colorbar is set by calling the :py:meth:`axes.tick_params` method on the axes object with a colour provided by ``theme``. .. _PlotTracerSurface: @@ -868,16 +867,16 @@ the content added to :file:`SalishSeaNowcast/docs/workers.rst` is: Automatic Code Formatting ========================= -The :kbd:`SalishSeaNowcast` package uses the `yapf`_ code formatting tool to maintain a coding style that is very close to `PEP 8`_. +The ``SalishSeaNowcast`` package uses the `black`_ code formatting tool to maintain a coding style that is very close to `PEP 8`_. -.. _yapf: https://github.com/google/yapf -.. _PEP 8: https://peps.python.org/pep-0008/ +.. _black: https://black.readthedocs.io/en/stable/ +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ -:command:`yapf` is installed as part of the :ref:`NowcastFiguresDevEnv` setup. +:command:`black` is installed as part of the :ref:`NowcastFiguresDevEnv` setup. -Before each commit of your figure module please run :program:`yapf` to automatically format your code. +Before each commit of your figure module please run :program:`black` to automatically format your code. For our example :py:mod:`~nowcast.figures.research.tracer_thalweg_and_surface` module the command would be: .. code-block:: bash - $ yapf --in-place nowcast/figures/research/tracer_thalweg_and_surface.py + $ black nowcast/figures/research/tracer_thalweg_and_surface.py diff --git a/docs/figures/fig_dev_env.rst b/docs/figures/fig_dev_env.rst index 287ade88..232e61cd 100644 --- a/docs/figures/fig_dev_env.rst +++ b/docs/figures/fig_dev_env.rst @@ -23,13 +23,13 @@ Nowcast Figures Development Environment *************************************** This section explains how to set up an isolated `Conda`_ environment for nowcast web site figure development and testing. -The environment will have both the :kbd:`SalishSeaNowcast` nowcast system package, -and the :kbd:`salishsea-site` web site app package installed in it, +The environment will have both the ``SalishSeaNowcast`` nowcast system package, +and the ``salishsea-site`` web site app package installed in it, along with all of their dependencies. .. _Conda: https://conda.io/en/latest/ -The :kbd:`SalishSeaNowcast` and :kbd:`salishsea-site` packages use some Python language features that are not available in versions prior to Python 3.6, +The ``SalishSeaNowcast`` and ``salishsea-site`` packages use some Python language features that are not available in versions prior to Python 3.6, in particular: * `formatted string literals`_ @@ -79,7 +79,7 @@ you can create and activate a figures development environment with these command (nowcast-fig-dev)$ python3 -m pip install --editable ../salishsea-site/ (nowcast-fig-dev)$ python3 -m pip install --editable . -The :kbd:`--editable` option in the :command:`pip install` command above installs the packages from the cloned repos via symlinks so that the installed packages will be automatically updated as the repos evolve. +The ``--editable`` option in the :command:`pip install` command above installs the packages from the cloned repos via symlinks so that the installed packages will be automatically updated as the repos evolve. To deactivate the environment use: diff --git a/docs/figures/fig_module_tips.rst b/docs/figures/fig_module_tips.rst index f78f05b1..03cf89ea 100644 --- a/docs/figures/fig_module_tips.rst +++ b/docs/figures/fig_module_tips.rst @@ -22,8 +22,7 @@ Figure Module Tips ****************** -This section contains pointers to useful visualization functions in the :kbd:`SalishSeaTools` package. -It also contains pointers to website figure module functions that do common things so that you can copy code rather than having to reinvent the wheel. +This section contains pointers to website figure module functions that do common things so that you can copy code rather than having to reinvent the wheel. Format Date/Time Tick Labels on an Axes diff --git a/docs/figures/index.rst b/docs/figures/index.rst index a8e613bc..9c149579 100644 --- a/docs/figures/index.rst +++ b/docs/figures/index.rst @@ -29,7 +29,7 @@ In summary: and how to develop and test a figure module with the help of a Jupyter notebook. * The :py:func:`make_figure` functions from figure modules are called by the nowcast system :py:mod:`nowcast.workers.make_plots` worker. - The figure object that a :py:func:`make_figure` function returns is rendered to storage on the :kbd:`salishsea.eos.ubc.ca` figures server. + The figure object that a :py:func:`make_figure` function returns is rendered to storage on the ``salishsea.eos.ubc.ca`` figures server. See :ref:`CallingMakeFigureFunctionsInTheMakePlotsWorker` for details of variables that the :py:mod:`~nowcast.workers.make_plots` worker can provide to :py:func:`make_figure` functions, and how to store the figure to the figures server. diff --git a/docs/figures/make_figure_calls.rst b/docs/figures/make_figure_calls.rst index e6dddc1e..6e752ef0 100644 --- a/docs/figures/make_figure_calls.rst +++ b/docs/figures/make_figure_calls.rst @@ -65,19 +65,19 @@ The :py:mod:`~nowcast.workers.make_plots` worker organizes figures by NEMO run t The :command:`python -m nowcast.workers.make_plots -h` command will show you a list of the run types and plot types. At present the run types are: -* :kbd:`nowcast` -* :kbd:`nowcast-green` -* :kbd:`forecast` -* :kbd:`forecast2` +* ``nowcast`` +* ``nowcast-green`` +* ``forecast`` +* ``forecast2`` and the plot types are: -* :kbd:`research` -* :kbd:`comparison` -* :kbd:`publish` +* ``research`` +* ``comparison`` +* ``publish`` -:py:mod:`~nowcast.workers.make_plots` also accepts a :kbd:`--run-date` to specify the date of the daily nowcast system NEMO run to create the figure for. -Without :kbd:`--run-date` today's date is used. +:py:mod:`~nowcast.workers.make_plots` also accepts a ``--run-date`` to specify the date of the daily nowcast system NEMO run to create the figure for. +Without ``--run-date`` today's date is used. The :py:func:`~nowcast.workers.make_plots.make_plots` function uses paths defined in the nowcast system configuration file (:file:`SalishSeaNowcast/config/nowcast.yaml`) @@ -109,8 +109,8 @@ To use the :py:mod:`nowcast.figures.research.tracer_thalweg_and_surface` to prod return fig_functions That function presently loads only one results dataset, -from the hourly :kbd:`SalishSea_*_ptrc_T.nc` file from a :kbd:`nowcast-green` run. -If you wanted to also produce a salinity thalweg and surface figure you would need to add a line to load the corresponding :kbd:`grid_T.nc` dataset, +from the hourly ``SalishSea_*_ptrc_T.nc`` file from a ``nowcast-green`` run. +If you wanted to also produce a salinity thalweg and surface figure you would need to add a line to load the corresponding ``grid_T.nc`` dataset, something like: .. code-block:: python @@ -128,15 +128,15 @@ Each :py:func:`make_figure` call that we want :py:mod:`~nowcast.workers.make_plo } The key, -:kbd:`nitrate_thalweg_and_surface` is the the root part of the file name into which the figure will be rendered. -If :py:mod:`~nowcast.workers.make_plots` is run with the command-line options :kbd:`nowcast-green research --run-date 2017-04-29`, +``nitrate_thalweg_and_surface`` is the the root part of the file name into which the figure will be rendered. +If :py:mod:`~nowcast.workers.make_plots` is run with the command-line options ``nowcast-green research --run-date 2017-04-29``, it will stored the rendered figure with the file name :file:`nitrate_thalweg_and_surface_29apr17.svg`. The value is a :py:obj:`dict` that defines how to call the :py:func:`make_figure` function. It has 2 required key/value pairs, and 2 optional ones. -The :kbd:`function` key is required. +The ``function`` key is required. Its value is the name of the website figure module and the function in it to call (i.e. :py:func:`make_figure`) in dotted notation. *Note that the value is a function object, so it is* **not** *enclosed in quotes.* The website figure module must be imported at the top of the :py:mod:`~nowcast.workers.make_plots` module; e.g. @@ -145,18 +145,18 @@ The website figure module must be imported at the top of the :py:mod:`~nowcast.w from nowcast.figures.research import tracer_thalweg_and_surface -The :kbd:`args` key is required. +The ``args`` key is required. Its value is is a :py:obj:`tuple` containing the positional arguments that :py:func:`make_figure` is to be called with. -The :kbd:`kwargs` key is optional. +The ``kwargs`` key is optional. Its value is a :py:obj:`dict` containing the keyword arguments and their values that :py:func:`make_plots` is to be called with. -If no keyword arguments are needed you can omit :kbd:`kwargs`. +If no keyword arguments are needed you can omit ``kwargs``. -The other optional key is :kbd:`format`. +The other optional key is ``format``. Its value is the image format to use to store the rendered figure. -It defaults to :kbd:`svg`, +It defaults to ``svg``, our preferred figure image format because it is a resolution-independent vector format. -The :kbd:`format` key is provided for the occassional special instances when we want to save images as :kbd:`png` bitmap images. +The ``format`` key is provided for the occasional special instances when we want to save images as ``png`` bitmap images. So, the :py:obj:`fig_functions` item: @@ -215,15 +215,15 @@ We can test that we have set up the necessary dataset loading and registered our The command line elements are: - * :kbd:`-m` to tell Python to run a module - * :kbd:`nowcast.workers.make_plots`, the module to run - * :kbd:`config/nowcast.yaml` the path and file name of the nowcast system configuration file - * :kbd:`nowcast-green`, the run type - * :kbd:`research`, the plots type - * :kbd:`--debug` to send logging output to the terminal and *not* communicate with the nowcast system manager process (**very important**) - * :kbd:`--test-figure` to produce a test figure - * :kbd:`nitrate_thalweg_and_surface` the key of the :py:func:`make_figure` call to test - * :kbd:`--run-date` to say what date's run results to render the figure for + * ``-m`` to tell Python to run a module + * ``nowcast.workers.make_plots``, the module to run + * ``config/nowcast.yaml``, the path and file name of the nowcast system configuration file + * ```nowcast-green``, the run type + * ``research``, the plots type + * ``--debug`` to send logging output to the terminal and *not* communicate with the nowcast system manager process (**very important**) + * ``--test-figure`` to produce a test figure + * ``nitrate_thalweg_and_surface``, the key of the :py:func:`make_figure` call to test + * ``--run-date``, to say what date's run results to render the figure for The output of a successful test should look something like:: @@ -233,7 +233,7 @@ We can test that we have set up the necessary dataset loading and registered our 2017-05-05 17:11:16,358 DEBUG [make_plots] starting nowcast.figures.research.tracer_thalweg_and_surface.make_figure 2017-05-05 17:11:18,645 INFO [make_plots] /results/nowcast-sys/figures/test/nowcast-green/29apr17/nitrate_thalweg_and_surface_29apr17.svg saved 2017-05-05 17:11:18,646 INFO [make_plots] research plots for 2017-04-29 nowcast-green completed - 2017-05-05 17:11:18,647 DEBUG [make_plots] **debug mode** message that would have been sent to manager: (success nowcast-green research nowcast-green reseach plots produced) + 2017-05-05 17:11:18,647 DEBUG [make_plots] **debug mode** message that would have been sent to manager: (success nowcast-green research nowcast-green research plots produced) 2017-05-05 17:11:18,647 DEBUG [make_plots] shutting down It is particularly important that your output contains the line that tells you that your figure was saved:: diff --git a/docs/figures/site_view_fig_metadata.rst b/docs/figures/site_view_fig_metadata.rst index 5e82b8cf..2192ba9d 100644 --- a/docs/figures/site_view_fig_metadata.rst +++ b/docs/figures/site_view_fig_metadata.rst @@ -25,11 +25,11 @@ SalishSeaCast Web Page View Figure Metadata This section discusses: * how to add figure metadata to the :py:mod:`salishsea_site.views.salishseacast` module to make a figure appear on a web page -* how to run a local instance of the :kbd:`salishsea` website to confirm that the figure is on the web page +* how to run a local instance of the ``salishsea`` website to confirm that the figure is on the web page We'll use the :py:mod:`nowcast.figures.research.tracer_thalweg_and_surface` figure module as an example. -You should run your local :kbd:`salishsea` website server for testing in a :ref:`NowcastFiguresDevEnv`. +You should run your local ``salishsea`` website server for testing in a :ref:`NowcastFiguresDevEnv`. You can activate it with: .. code-block:: bash @@ -49,7 +49,7 @@ The `salishsea.eos.ubc.ca site web app`_ gathers figures that have been rendered Each row on the https://salishsea.eos.ubc.ca/nemo/results/ page contains links to pages that are generated from a page template by a view function in the :py:mod:`salishsea_site.views.salishseacast` module. Each view function uses a list of :py:class:`salishsea_site.views.salishseacast.FigureMetadata` objects that is also defined in the :py:mod:`salishsea_site.views.salishseacast` module. The :py:class:`~salishsea_site.views.salishseacast.FigureMetadata` objects set the title for the figure that will appear on the web page, -and the :kbd:`svg_name` of the figure files rendered by the :py:mod:`make_plots` worker. +and the ``svg_name`` of the figure files rendered by the :py:mod:`make_plots` worker. So, to add a figure rendered from our :py:mod:`nowcast.figures.research.tracer_thalweg_and_surface` figure module to the :guilabel:`Biology` page, @@ -62,15 +62,15 @@ we add a :py:class:`~salishsea_site.views.salishseacast.FigureMetadata` object t svg_name='nitrate_thalweg_and_surface', ) -The value of the :kbd:`title` attribute appears in :guilabel:`Plots` list on the page as a link to the figure lower down on the page, +The value of the ``title`` attribute appears in :guilabel:`Plots` list on the page as a link to the figure lower down on the page, and it appears as a heading above the figure image. -The value of the :kbd:`svg_name` attribute is key that we used to register our figure function module in the :py:mod:`make_plots` worker. +The value of the ``svg_name`` attribute is key that we used to register our figure function module in the :py:mod:`make_plots` worker. Recall that the key is also used as the root part of the file name into which the figure is rendered. That is: -* We :ref:`registered a call ` to the :py:func:`nowcast.figures.research.tracer_thalweg_and_surface.make_figure` function in the :py:func:`nowcast.workers.make_plots._prep_nowcast_green_research_fig_functions` function using the key :kbd:`nitrate_thalweg_and_surface` to produce a nitrate thalweg and surface figure -* When the :py:mod:`make_plots` was run with the command-line options :kbd:`nowcast-green research --run-date 2017-04-29` it stored the rendered figure with the file name :file:`nitrate_thalweg_and_surface_29apr17.svg` +* We :ref:`registered a call ` to the :py:func:`nowcast.figures.research.tracer_thalweg_and_surface.make_figure` function in the :py:func:`nowcast.workers.make_plots._prep_nowcast_green_research_fig_functions` function using the key ``nitrate_thalweg_and_surface`` to produce a nitrate thalweg and surface figure +* When the :py:mod:`make_plots` was run with the command-line options ``nowcast-green research --run-date 2017-04-29`` it stored the rendered figure with the file name :file:`nitrate_thalweg_and_surface_29apr17.svg` The order of :py:class:`~salishsea_site.views.salishseacast.FigureMetadata` objects in the :py:obj:`~salishsea_site.views.salishseacast.biology_figures` list determines the order in which the figures appear on the web page. @@ -123,9 +123,9 @@ Testing the Website View but the PID number will be different. The web server is now running in this terminal session. - You can stop it with :kbd:`Ctrl-C` when you are finished. + You can stop it with :kbd:`Control-c` when you are finished. -#. Use your browser to navigate to :kbd:`http://localhost:6543/nemo/results/`. +#. Use your browser to navigate to ``http://localhost:6543/nemo/results/``. From there you should be able to navigate to the page that will show you the figures for the date that you ran the :py:mod:`make_plots` worker for; for our test of the :py:mod:`nowcast.figures.research.tracer_thalweg_and_surface` figure module, @@ -140,15 +140,15 @@ Testing the Website View Automatic Code Formatting ========================= -The :kbd:`salishsea_site` package uses the `yapf`_ code formatting tool to maintain a coding style that is very close to `PEP 8`_. +The :kbd:`salishsea_site` package uses the`black`_ code formatting tool to maintain a coding style that is very close to `PEP 8`_. -.. _yapf: https://github.com/google/yapf -.. _PEP 8: https://peps.python.org/pep-0008/ +.. _black: https://black.readthedocs.io/en/stable/ +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ -:command:`yapf` is installed as part of the :ref:`NowcastFiguresDevEnv` setup. +:command:`black` is installed as part of the :ref:`NowcastFiguresDevEnv` setup. -Before each commit of the :py:mod:`salishsea_site.views.salishseacast` module please run :program:`yapf` to automatically format the code with the command: +Before each commit of the :py:mod:`salishsea_site.views.salishseacast` module please run :program:`black` to automatically format the code with the command: .. code-block:: bash - $ yapf --in-place salishsea_site/views/salishseacast.py + $ black salishsea_site/views/salishseacast.py diff --git a/docs/figures/website_theme.rst b/docs/figures/website_theme.rst index bc598392..d4b4ffe6 100644 --- a/docs/figures/website_theme.rst +++ b/docs/figures/website_theme.rst @@ -23,7 +23,7 @@ Website Theme ************* The :py:mod:`nowcast.figures.website_theme` module provides the definition of colours and fonts that figure modules must use in order to ensure consistency from one to the next, -and with the :kbd:`salishsea.eos.ubc.ca` site NEMO results section styling. +and with the ``salishsea.eos.ubc.ca`` site NEMO results section styling. The module contains: @@ -38,10 +38,10 @@ The module contains: :py:const:`~nowcast.figures.website_theme.SITE_BACKGROUND_COLOUR` ================================================================= -:py:const:`SITE_BACKGROUND_COLOUR` is the hex code for the :kbd:`salishsea.eos.ubc.ca/` pages background colour, +:py:const:`SITE_BACKGROUND_COLOUR` is the hex code for the ``salishsea.eos.ubc.ca/`` pages background colour, from the https://bootswatch.com/superhero/ theme. It is defined explicitly to make it obvious in the :py:mod:`~nowcast.figures.website_theme` module. -It is used in the :py:const:`COLOURS` dictionary as :kbd:`COLOURS['figure']['facecolor']` so that you can apply it to :py:class:`~matplotlib.figure.Figure` objects by creating them with calls like: +It is used in the :py:const:`COLOURS` dictionary as ``COLOURS['figure']['facecolor']`` so that you can apply it to :py:class:`~matplotlib.figure.Figure` objects by creating them with calls like: .. code-block:: python diff --git a/docs/pkg_development.rst b/docs/pkg_development.rst index 3f3e8696..bbe3a0f8 100644 --- a/docs/pkg_development.rst +++ b/docs/pkg_development.rst @@ -18,9 +18,9 @@ .. _SalishSeaNowcastPackagedDevelopment: -******************************************* -:kbd:`SalishSeaNowcast` Package Development -******************************************* +**************************************** +``SalishSeaNowcast`` Package Development +**************************************** +------------------------------+---------------------------------------------------------------------------------------------------------------------+ | **Continuous Integration** | .. image:: https://github.com/SalishSeaCast/SalishSeaNowcast/actions/workflows/pytest-with-coverage.yaml/badge.svg | @@ -68,7 +68,7 @@ | | :target: https://github.com/pypa/hatch | +------------------------------+---------------------------------------------------------------------------------------------------------------------+ -The :kbd:`SalishSeaNowcast` package is a collection of Python modules associated with +The ``SalishSeaNowcast`` package is a collection of Python modules associated with running the SalishSeaCast ocean models in a daily nowcast/forecast mode. The package uses the `NEMO_Nowcast`_ framework to implement the :ref:`SalishSeaNowcastSystem`. @@ -84,7 +84,7 @@ Python Version :target: https://docs.python.org/3.12/ :alt: Python Version -The :kbd:`SalishSeaNowcast` package is developed and tested using `Python`_ 3.12. +The ``SalishSeaNowcast`` package is developed and tested using `Python`_ 3.12. .. _Python: https://www.python.org/ @@ -114,14 +114,14 @@ Development Environment Setting up an isolated development environment using `Conda`_ is recommended. Assuming that you have `Miniconda`_ installed, -you can create and activate an environment called :kbd:`salishsea-nowcast` that will have all of the Python packages necessary for development, +you can create and activate an environment called ``salishsea-nowcast`` that will have all of the Python packages necessary for development, testing, and building the documentation with the commands below. .. _Conda: https://conda.io/en/latest/ .. _Miniconda: https://docs.conda.io/en/latest/miniconda.html -:kbd:`SalishSeaNowcast` depends on a collection of other Python packages developed by the SalishSeaCast project and friends: +``SalishSeaNowcast`` depends on a collection of other Python packages developed by the SalishSeaCast project and friends: * `NEMO_Nowcast`_ * `moad_tools`_ @@ -156,8 +156,8 @@ you can clone those repos with: If you already have clones of those repos, please ensure that they are up to date. -Assuming that those repos are cloned beside your :kbd:`SalishSeaNowcast` clone, -the commands below install the packages into your :kbd:`salishsea-nowcast` development environment. +Assuming that those repos are cloned beside your ``SalishSeaNowcast`` clone, +the commands below install the packages into your ``salishsea-nowcast`` development environment. .. code-block:: bash @@ -177,7 +177,7 @@ the commands below install the packages into your :kbd:`salishsea-nowcast` devel (salishsea-nowcast)$ python3 -m pip install --editable ../FVCOM-Cmd (salishsea-nowcast)$ python3 -m pip install --editable . -The :kbd:`--editable` option in the :command:`pip install` command above installs the packages from the cloned repos via symlinks so that the installed packages will be automatically updated as the repos evolve. +The ``--editable`` option in the :command:`pip install` command above installs the packages from the cloned repos via symlinks so that the installed packages will be automatically updated as the repos evolve. To deactivate the environment use: @@ -198,7 +198,7 @@ Coding Style :target: https://black.readthedocs.io/en/stable/ :alt: The uncompromising Python code formatter -The :kbd:`SalishSeaNowcast` package uses Git pre-commit hooks managed by `pre-commit`_ +The ``SalishSeaNowcast`` package uses Git pre-commit hooks managed by `pre-commit`_ to maintain consistent code style and and other aspects of code, docs, and repo QA. @@ -231,10 +231,10 @@ Building the Documentation :target: https://salishsea-nowcast.readthedocs.io/en/latest/ :alt: Documentation Status -The documentation for the :kbd:`SalishSeaNowcast` package is written in `reStructuredText`_ and converted to HTML using `Sphinx`_. +The documentation for the ``SalishSeaNowcast`` package is written in `reStructuredText`_ and converted to HTML using `Sphinx`_. Creating a :ref:`SalishSeaNowcastDevelopmentEnvironment` as described above includes the installation of Sphinx. Building the documentation is driven by the :file:`docs/Makefile`. -With your :kbd:`salishsea-nowcast` development environment activated, +With your ``salishsea-nowcast`` development environment activated, use: .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html @@ -295,7 +295,7 @@ Link Checking the Documentation Sphinx also provides a link checker utility which can be run to find broken or redirected links in the docs. -With your :kbd:`salishsea-nowcast` environment activated, +With your ``salishsea-nowcast`` environment activated, use: .. code-block:: bash @@ -529,12 +529,12 @@ The output looks something like:: Running the Unit Tests ====================== -The test suite for the :kbd:`SalishSeaNowcast` package is in :file:`SalishSeaNowcast/tests/`. +The test suite for the ``SalishSeaNowcast`` package is in :file:`SalishSeaNowcast/tests/`. The `pytest`_ tool is used for test parametrization and as the test runner for the suite. .. _pytest: https://docs.pytest.org/en/latest/ -With your :kbd:`salishsea-nowcast` development environment activated, +With your ``salishsea-nowcast`` development environment activated, use: .. code-block:: bash @@ -652,7 +652,7 @@ Continuous Integration :target: https://github.com/SalishSeaCast/SalishSeaNowcast/actions?query=workflow:pytest-with-coverage :alt: GitHub Workflow Status -The :kbd:`SalishSeaNowcast` package unit test suite is run and a coverage report is generated whenever changes are pushed to GitHub. +The ``SalishSeaNowcast`` package unit test suite is run and a coverage report is generated whenever changes are pushed to GitHub. The results are visible on the `repo actions page`_, from the green checkmarks beside commits on the `repo commits page`_, or from the green checkmark to the left of the "Latest commit" message on the `repo code overview page`_ . @@ -677,7 +677,7 @@ Version Control Repository :target: https://github.com/SalishSeaCast/SalishSeaNowcast :alt: Git on GitHub -The :kbd:`SalishSeaNowcast` package code and documentation source files are available as a `Git`_ repository at https://github.com/SalishSeaCast/SalishSeaNowcast. +The ``SalishSeaNowcast`` package code and documentation source files are available as a `Git`_ repository at https://github.com/SalishSeaCast/SalishSeaNowcast. .. _Git: https://git-scm.com/ diff --git a/docs/workers.rst b/docs/workers.rst index ae1a66b3..aaf96eee 100644 --- a/docs/workers.rst +++ b/docs/workers.rst @@ -65,8 +65,8 @@ Workers .. _CollectWeatherWorker: -:kbd:`collect_weather` ------------------------ +``collect_weather`` +-------------------- .. automodule:: nowcast.workers.collect_weather :members: main @@ -74,8 +74,8 @@ Workers .. _DownloadWeatherWorker: -:kbd:`download_weather` ------------------------ +``download_weather`` +-------------------- .. automodule:: nowcast.workers.download_weather :members: main @@ -83,8 +83,8 @@ Workers .. _CropGribsWorker: -:kbd:`crop_gribs` ---------------------- +``crop_gribs`` +------------------ .. automodule:: nowcast.workers.crop_gribs :members: main @@ -92,29 +92,29 @@ Workers .. _GribToNetcdfWorker: -:kbd:`grib_to_netcdf` ---------------------- +``grib_to_netcdf`` +------------------ .. automodule:: nowcast.workers.grib_to_netcdf :members: main -:kbd:`collect_river_data` -------------------------- +``collect_river_data`` +---------------------- .. automodule:: nowcast.workers.collect_river_data :members: main -:kbd:`make_runoff_file` ------------------------ +``make_runoff_file`` +-------------------- .. automodule:: nowcast.workers.make_runoff_file :members: main -:kbd:`make_v202111_runoff_file` -------------------------------- +``make_v202111_runoff_file`` +---------------------------- .. automodule:: nowcast.workers.make_v202111_runoff_file :members: main @@ -122,8 +122,8 @@ Workers .. _CollectNeahBaySshWorker: -:kbd:`collect_NeahBay_ssh` --------------------------- +``collect_NeahBay_ssh`` +----------------------- .. automodule:: nowcast.workers.collect_NeahBay_ssh :members: main @@ -131,8 +131,8 @@ Workers .. _MakeSshFilesWorker: -:kbd:`make_ssh_files` ---------------------- +``make_ssh_files`` +------------------ .. automodule:: nowcast.workers.make_ssh_files :members: main @@ -140,8 +140,8 @@ Workers .. _DownloadLiveOceanWorker: -:kbd:`download_live_ocean` --------------------------- +``download_live_ocean`` +----------------------- .. automodule:: nowcast.workers.download_live_ocean :members: main @@ -149,8 +149,8 @@ Workers .. _MakeLiveOceanFilesWorker: -:kbd:`make_live_ocean_files` ----------------------------- +``make_live_ocean_files`` +------------------------- .. automodule:: nowcast.workers.make_live_ocean_files :members: main @@ -158,36 +158,36 @@ Workers .. _UploadForcingWorker: -:kbd:`upload_forcing` ---------------------- +``upload_forcing`` +------------------ .. automodule:: nowcast.workers.upload_forcing :members: main -:kbd:`make_forcing_links` -------------------------- +``make_forcing_links`` +---------------------- .. automodule:: nowcast.workers.make_forcing_links :members: main -:kbd:`run_NEMO` ---------------- +``run_NEMO`` +------------ .. automodule:: nowcast.workers.run_NEMO :members: main -:kbd:`run_NEMO_agrif` ---------------------- +``run_NEMO_agrif`` +------------------ .. automodule:: nowcast.workers.run_NEMO_agrif :members: main -:kbd:`run_NEMO_hindcast` ------------------------- +``run_NEMO_hindcast`` +--------------------- .. automodule:: nowcast.workers.run_NEMO_hindcast :members: main @@ -195,71 +195,71 @@ Workers .. _WatchNEMO-Worker: -:kbd:`watch_NEMO` ------------------ +``watch_NEMO`` +-------------- .. automodule:: nowcast.workers.watch_NEMO :members: main -:kbd:`watch_NEMO_agrif` ------------------------ +``watch_NEMO_agrif`` +-------------------- .. automodule:: nowcast.workers.watch_NEMO_agrif :members: main -:kbd:`watch_NEMO_hindcast` --------------------------- +``watch_NEMO_hindcast`` +----------------------- .. automodule:: nowcast.workers.watch_NEMO_hindcast :members: main -:kbd:`make_turbidity_file` --------------------------- +``make_turbidity_file`` +----------------------- .. automodule:: nowcast.workers.make_turbidity_file :members: main -:kbd:`make_fvcom_boundary` --------------------------- +``make_fvcom_boundary`` +----------------------- .. automodule:: nowcast.workers.make_fvcom_boundary :members: main -:kbd:`make_fvcom_rivers_forcing` --------------------------------- +``make_fvcom_rivers_forcing`` +----------------------------- .. automodule:: nowcast.workers.make_fvcom_rivers_forcing :members: main -:kbd:`make_fvcom_atmos_forcing` -------------------------------- +``make_fvcom_atmos_forcing`` +---------------------------- .. automodule:: nowcast.workers.make_fvcom_atmos_forcing :members: main -:kbd:`upload_fvcom_atmos_forcing` ---------------------------------- +``upload_fvcom_atmos_forcing`` +------------------------------ .. automodule:: nowcast.workers.upload_fvcom_atmos_forcing :members: main -:kbd:`run_fvcom` ----------------- +``run_fvcom`` +------------- .. automodule:: nowcast.workers.run_fvcom :members: main -:kbd:`watch_fvcom` ------------------- +``watch_fvcom`` +--------------- .. automodule:: nowcast.workers.watch_fvcom :members: main @@ -267,8 +267,8 @@ Workers .. _MakeWW3WindFile-Worker: -:kbd:`make_ww3_wind_file` -------------------------- +``make_ww3_wind_file`` +---------------------- .. automodule:: nowcast.workers.make_ww3_wind_file :members: main @@ -276,85 +276,85 @@ Workers .. _MakeWW3CurrentFile-Worker: -:kbd:`make_ww3_current_file` ----------------------------- +``make_ww3_current_file`` +------------------------- .. automodule:: nowcast.workers.make_ww3_current_file :members: main -:kbd:`run_ww3` ---------------- +``run_ww3`` +------------ .. automodule:: nowcast.workers.run_ww3 :members: main -:kbd:`watch_ww3` ------------------ +``watch_ww3`` +-------------- .. automodule:: nowcast.workers.watch_ww3 :members: main -:kbd:`download_results` ------------------------ +``download_results`` +-------------------- .. automodule:: nowcast.workers.download_results :members: main -:kbd:`make_averaged_dataset` ----------------------------- +``make_averaged_dataset`` +------------------------- .. automodule:: nowcast.workers.make_averaged_dataset :members: main -:kbd:`archive_tarball` ----------------------- +``archive_tarball`` +------------------- .. automodule:: nowcast.workers.archive_tarball :members: main -:kbd:`split_results` --------------------- +``split_results`` +----------------- .. automodule:: nowcast.workers.split_results :members: main -:kbd:`download_wwatch3_results` -------------------------------- +``download_wwatch3_results`` +---------------------------- .. automodule:: nowcast.workers.download_wwatch3_results :members: main -:kbd:`download_fvcom_results` ------------------------------ +``download_fvcom_results`` +-------------------------- .. automodule:: nowcast.workers.download_fvcom_results :members: main -:kbd:`get_onc_ctd` ------------------- +``get_onc_ctd`` +--------------- .. automodule:: nowcast.workers.get_onc_ctd :members: main -:kbd:`update_forecast_datasets` -------------------------------- +``update_forecast_datasets`` +---------------------------- .. automodule:: nowcast.workers.update_forecast_datasets :members: main -:kbd:`ping_erddap` ------------------- +``ping_erddap`` +--------------- .. automodule:: nowcast.workers.ping_erddap :members: main @@ -362,36 +362,36 @@ Workers .. _MakePlotsWorker: -:kbd:`make_plots` ------------------ +``make_plots`` +-------------- .. automodule:: nowcast.workers.make_plots :members: main -:kbd:`make_surface_current_tiles` ---------------------------------- +``make_surface_current_tiles`` +------------------------------ .. automodule:: nowcast.workers.make_surface_current_tiles :members: main -:kbd:`make_feeds` ------------------ +``make_feeds`` +-------------- .. automodule:: nowcast.workers.make_feeds :members: main -:kbd:`clear_checklist` ----------------------- +``clear_checklist`` +------------------- .. automodule:: nemo_nowcast.workers.clear_checklist :members: main -:kbd:`rotate_logs` ------------------- +``rotate_logs`` +--------------- .. automodule:: nemo_nowcast.workers.rotate_logs :members: main @@ -410,22 +410,22 @@ Worker Utility Functions Special Workers --------------- -:kbd:`launch_remote_worker` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``launch_remote_worker`` +^^^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: nowcast.workers.launch_remote_worker :members: main -:kbd:`rotate_hindcast_logs` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``rotate_hindcast_logs`` +^^^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: nowcast.workers.rotate_hindcast_logs :members: main -:kbd:`next_workers` Module -========================== +:py:mod:`next_workers` Module +============================= .. automodule:: nowcast.next_workers :members: diff --git a/nowcast/figures/fvcom/publish/second_narrows_current.py b/nowcast/figures/fvcom/publish/second_narrows_current.py index 926478ea..b6ab612d 100644 --- a/nowcast/figures/fvcom/publish/second_narrows_current.py +++ b/nowcast/figures/fvcom/publish/second_narrows_current.py @@ -55,7 +55,7 @@ def make_figure( :arg fvcom_stns_datasets: Dictionary of VHFR FVCOM model tide gauge station sea surface height time series of py:class:`xarray.Dataset` objects keyed by model - model configuration (:kbd:`x2`, :kbd:`r12`). + model configuration (``x2``, ``r12``). :type fvcom_stns_datasets: :py:class:`dict` :arg obs_dataset: Observed horizontal ADCP station sea water current time series dataset. diff --git a/nowcast/figures/fvcom/publish/tide_stn_water_level.py b/nowcast/figures/fvcom/publish/tide_stn_water_level.py index 48f52423..66836ba4 100644 --- a/nowcast/figures/fvcom/publish/tide_stn_water_level.py +++ b/nowcast/figures/fvcom/publish/tide_stn_water_level.py @@ -19,7 +19,7 @@ """Produce a figure that shows water levels at a tide gauge station calculated by the VHFR FVCOM and SalishSeaCast NEMO models, and predicted and observed water levels from the CHS -:kbd:`https://ws-shc.qc.dfo-mpo.gc.ca/` water levels web service. +``https://ws-shc.qc.dfo-mpo.gc.ca/`` water levels web service. Testing notebook for this module is https://nbviewer.org/github/SalishSeaCast/SalishSeaNowcast/blob/main/notebooks/figures/fvcom/publish/TestTideStnWaterLevel.ipynb @@ -55,8 +55,8 @@ def make_figure( ): """Plot water levels calculated by the VHFR FVCOM and SalishSeaCast NEMO models, and predicted and observed water levels from the CHS - :kbd:`https://ws-shc.qc.dfo-mpo.gc.ca/` water levels web service for the - tide gauge station at :kbd:`place`. + ``https://ws-shc.qc.dfo-mpo.gc.ca/`` water levels web service for the + tide gauge station at ``place``. :arg str place: Tide gauge station name; must be a key in :py:obj:`salishsea_tools.places.PLACES`. @@ -64,7 +64,7 @@ def make_figure( :arg fvcom_ssh_datasets: Dictionary of VHFR FVCOM model tide gauge station sea surface height time series of py:class:`xarray.Dataset` objects keyed by model - model configuration (:kbd:`x2`, :kbd:`r12`). + model configuration (``x2``, ``r12``). :type fvcom_ssh_datasets: :py:class:`dict` :arg str nemo_ssh_dataset_url_tmpl: ERDDAP URL template for SalishSeaCast diff --git a/nowcast/figures/publish/compare_tide_prediction_max_ssh.py b/nowcast/figures/publish/compare_tide_prediction_max_ssh.py index d8b2d563..a5f9b114 100644 --- a/nowcast/figures/publish/compare_tide_prediction_max_ssh.py +++ b/nowcast/figures/publish/compare_tide_prediction_max_ssh.py @@ -79,7 +79,7 @@ def make_figure( """Plot tidal prediction and models water level timeseries, storm surge residual timeseries, sea surface height contours on a Salish Sea map, and summary text for the tide gauge station at - :kbd:`place`. + ``place``. :arg str place: Tide gauge station name; must be a key in :py:obj:`salishsea_tools.places.PLACES`. diff --git a/nowcast/figures/publish/pt_atkinson_tide.py b/nowcast/figures/publish/pt_atkinson_tide.py index 028c4777..741bb26e 100644 --- a/nowcast/figures/publish/pt_atkinson_tide.py +++ b/nowcast/figures/publish/pt_atkinson_tide.py @@ -49,7 +49,7 @@ def make_figure( theme=nowcast.figures.website_theme, ): """Plot the tidal cycle at Point Atkinson during a 4 week period centred - around the model results in :kbd:`grid_T` with that period indicated on + around the model results in ``grid_T`` with that period indicated on the graph. :arg grid_T_hr: Hourly tracer results dataset from NEMO. diff --git a/nowcast/figures/research_ferries.py b/nowcast/figures/research_ferries.py index 7cde030b..076ef81e 100644 --- a/nowcast/figures/research_ferries.py +++ b/nowcast/figures/research_ferries.py @@ -187,9 +187,9 @@ def ferry_salinity(ferry_data_dir, route_name, dmy, step=1): :arg str ferry_data_dir: storage file location for ONC ferry data. - :arg str route_name: name of a ferre route. HBDB, TWDP or TWSB. + :arg str route_name: name of a ferry route. ``HBDB``, ``TWDP`` or ``TWSB``. - :arg str dmy: today's date in :kbd:`ddmmmyy` format + :arg str dmy: today's date in ``ddmmmyy`` format :arg int step: selecting every nth data point diff --git a/nowcast/figures/shared.py b/nowcast/figures/shared.py index dc6e3f39..4570dba3 100644 --- a/nowcast/figures/shared.py +++ b/nowcast/figures/shared.py @@ -17,10 +17,10 @@ """A collection of functions for use by multiple figure modules in the -:kbd:`nowcast.figures` namespaces. +``nowcast.figures`` namespaces. .. note:: - These functions are intended for use *only* by :kbd:`nowcast.figures` + These functions are intended for use *only* by ``nowcast.figures`` modules. If you find that you want to use one of these functions outside of those namespaces please talk to the group about refactoring the function into @@ -61,8 +61,7 @@ def plot_map( :arg ax: Axes object to plot the map on. :type ax: :py:class:`matplotlib.axes.Axes` - :arg dict coastline: Pacific Northwest Coastline from matlab :kbd:`.mat` - file. + :arg dict coastline: Pacific Northwest Coastline from matlab ``.mat`` file. :arg 2-tuple lat_range: Latitude range to be plotted. @@ -150,8 +149,8 @@ def find_ssh_max(tide_gauge_stn, ssh_ts, ttide): :py:class:`~datetime.datetime` object. :type ssh_ts: :py:class:`collections.namedtuple` - :arg ttide: Tidal predictions data structure with :kbd:`time`, - :kbd:`pred_all`, :kbd:`pred_8`, and :kbd:`pred_noshallow` + :arg ttide: Tidal predictions data structure with ``time``, + ``pred_all``, ``pred_8``, and ``pred_noshallow`` columns. :type ttide: :py:class:`pandas.DataFrame` """ @@ -175,11 +174,11 @@ def correct_model_ssh(ssh_model, t_model, ttide): :type ssh_model: :py:class:`numpy.ndarray` :arg t_model: Model :py:class:`~datetime.datetime` objects corresponding to - :kbd:`ssh_model`. + ``ssh_model``. :type t_model: :py:class:`numpy.ndarray` - :arg ttide: Tidal predictions data structure with :kbd:`time`, - :kbd:`pred_all`, :kbd:`pred_8`, and :kbd:`pred_noshallow` + :arg ttide: Tidal predictions data structure with ``time``, + ``pred_all``, ``pred_8``, and ``pred_noshallow`` columns. :type ttide: :py:class:`pandas.DataFrame` @@ -205,11 +204,11 @@ def interp_to_model_time(t_model, values, t_values): :arg values: Values to be interpolated to model output times. :type values: :py:class:`numpy.ndarray` - :arg t_values: Times corresponding to :kbd:`values` as + :arg t_values: Times corresponding to ``values`` as :py:class:`~datetime.datetime` objects. :type t_values: :py:class:`numpy.ndarray` - :returns: Values interpolated to :kbd:`t_model` times. + :returns: Values interpolated to ``t_model`` times. :rtype: :py:class:`numpy.ndarray` """ epoch = t_model[0] @@ -237,9 +236,9 @@ def plot_risk_level_marker( perhaps from :py:func:`salishsea_tools.stormtools.storm_surge_risk_level`: :py:obj:`None` for no storm surge risk, - :kbd:`moderate risk` for water level between max tide + ``moderate risk`` for water level between max tide level and the half-way threshold, - and :kbd:`extreme risk` for water level above the + and ``extreme risk`` for water level above the half-way threshold :arg str marker: Marker identifier from :py:mod:`matplotlib.markers`. @@ -310,7 +309,7 @@ def plot_wind_arrow(ax, lon, lat, u_wind, v_wind, theme, wind_arrow_scale_factor def interpolate_tracer_to_depths( tracer, tracer_depths, interp_depths, tracer_mask, w_depths ): - """Calculate the interpolated value of :kbd:`tracer` at :kbd:`interp_depths` + """Calculate the interpolated value of ``tracer`` at ``interp_depths`` using linear interpolation. :arg tracer: Depth profile of a model tracer variable. @@ -323,8 +322,8 @@ def interpolate_tracer_to_depths( of the model variable or data quantity. :type interp_depths: :py:class:`numpy.ndarray` or number - :arg tracer_mask: Mask to use obtain the water sections of :kbd:`tracer` - and :kbd:`tracer_depths`; + :arg tracer_mask: Mask to use obtain the water sections of ``tracer`` + and ``tracer_depths``; i.e. a 1D slice of :py:attr:`tmask` from the mesh mask. :type tracer_mask: :py:class:`numpy.ndarray` @@ -338,11 +337,10 @@ def interpolate_tracer_to_depths( is zero-masked. :type w_depths: :py:class:`numpy.ndarray` - :returns: Value(s) of :kbd:`tracer` linearly interpolated to - :kbd:`interp_depths`. + :returns: Value(s) of ``tracer`` linearly interpolated to ``interp_depths``. :rtype: :py:class:`numpy.ndarray` or number - :raises: :py:exc:`ValueError` if any of the values in :kbd:`interp_depths` + :raises: :py:exc:`ValueError` if any of the values in ``interp_depths`` exceed the maximum model grid depth. """ try: @@ -361,12 +359,12 @@ def interpolate_tracer_to_depths( def localize_time(data_array, time_coord="time", local_datetime=None): - """Offset :kbd:`data_array` times to account for local time zone - difference from UTC and add :kbd:`tz_name` attribute to :kbd:`data_array`. + """Offset ``data_array`` times to account for local time zone + difference from UTC and add ``tz_name`` attribute to ``data_array``. .. note:: This function is intended for use just before presentation/output - of :kbd:`data_array`. It is strongly recommended to do all date/time + of ``data_array``. It is strongly recommended to do all date/time calculations in UTC to avoid time change issues. :param data_array: Data array or dataset object to adjust time values of. @@ -376,8 +374,8 @@ def localize_time(data_array, time_coord="time", local_datetime=None): :param local_datetime: Optional timezone-aware local date/time to use as basis to calculate offset from UTC. The 1st element - of :kbd:`data_array` is used when - :kbd:`local_datetime` is :py:class:`None`. + of ``data_array`` is used when + ``local_datetime`` is :py:class:`None`. :type local_datetime: :py:class:`arrow.Arrow` """ time_values = getattr(data_array, time_coord).values diff --git a/nowcast/figures/website_theme.py b/nowcast/figures/website_theme.py index 6c42411a..6ab66e65 100644 --- a/nowcast/figures/website_theme.py +++ b/nowcast/figures/website_theme.py @@ -22,7 +22,7 @@ from matplotlib.font_manager import FontProperties -#: The :kbd:`salishsea.eos.ubc.ca/nemo/` pages background colour, +#: The ``salishsea.eos.ubc.ca/nemo/`` pages background colour, #: from the https://bootswatch.com/superhero/ theme. SITE_BACKGROUND_COLOUR = "#2B3E50" diff --git a/nowcast/figures/wwatch3/wave_height_period.py b/nowcast/figures/wwatch3/wave_height_period.py index 1e94b19b..780daded 100644 --- a/nowcast/figures/wwatch3/wave_height_period.py +++ b/nowcast/figures/wwatch3/wave_height_period.py @@ -28,14 +28,12 @@ https://nbviewer.org/github/SalishSeaCast/SalishSeaNowcast/blob/main/notebooks/figures/wwatch3/DevelopWaveHeightPeriod.ipynb """ from contextlib import suppress -from pathlib import Path from types import SimpleNamespace import matplotlib.dates import matplotlib.pyplot as plt import moad_tools.observations import moad_tools.places -import requests import xarray from pandas.plotting import register_matplotlib_converters @@ -50,7 +48,7 @@ def make_figure( by the SoG WaveWatch3(TM) model, and observed wave heights and dominant wave periods from the NOAA NDBC https://www.ndbc.noaa.gov/data/realtime2/ web service for the wave buoy - at :kbd:`buoy`. + at ``buoy``. :arg str buoy: Wave buoy name; must be a key in :py:obj:`moad_tools.places.PLACES`. diff --git a/nowcast/workers/archive_tarball.py b/nowcast/workers/archive_tarball.py index d7320c8e..f8524ee7 100644 --- a/nowcast/workers/archive_tarball.py +++ b/nowcast/workers/archive_tarball.py @@ -59,7 +59,7 @@ def main(): worker.cli.add_argument( "dest_host", default="robot.graham", - help="Name of the host to move tarball and index files to. Default is :kbd:`robot.graham`.", + help="Name of the host to move tarball and index files to. Default is ``robot.graham``.", ) worker.run(archive_tarball, success, failure) return worker diff --git a/nowcast/workers/download_results.py b/nowcast/workers/download_results.py index e7fc0dac..bd4ecda7 100644 --- a/nowcast/workers/download_results.py +++ b/nowcast/workers/download_results.py @@ -55,7 +55,7 @@ def main(): worker.cli.add_argument( "--dest-host", default="localhost", - help="Name of the host to download results files to. Default is :kbd:`localhost`.", + help="Name of the host to download results files to. Default is ``localhost``.", ) worker.cli.add_date_option( "--run-date",