spelling

Author: Tom-Willemsen

.github/workflows/documentation.yml

@@ -14,9 +14,11 @@ jobs:
           python-version: "3.12"
       - name: install requirements
         run: pip install -e .[dev]
+      - name: run pytest
+        run: python -m pytest
       - name: run spellcheck
         run: sphinx-build -E -a -W --keep-going -b spelling doc _build
-  call_sphinx_builder:
+  build:
     uses: ISISComputingGroup/reusable-workflows/.github/workflows/sphinx.yml@main
     secrets: inherit
     with:

.gitignore

@@ -1,6 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+
 .idea/*
 .venv/
 ibex_developers_manual.egg-info/
 build/
 _build/
-doc/words.txt

doc/Editing-the-Wiki.md

@@ -4,8 +4,8 @@ This documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/
 plugin. Both of these tools have excellent online documentation.
 
 Sphinx is a widely-adopted structured documentation tool, which scales well even for very large projects - for example it 
-is used to build [python's documentation](https://docs.python.org/3/), the [linux kernel documentation](https://docs.kernel.org/), and 
-the [numpy documentation](https://numpy.org/doc/stable/).
+is used to build [Python's documentation](https://docs.python.org/3/), the [Linux kernel documentation](https://docs.kernel.org/), and 
+the [EPICS documentation](https://docs.epics-controls.org/en/latest/).
 
 ## Markdown
 
@@ -114,6 +114,17 @@ sphinx-build -b spelling doc _build
 There is an additional dictionary of allowed words in `doc/spelling_wordlist.txt`. This
 is used for words which we know are spelt correctly, but are not in the default dictionary.
 
+The word list can be kept in order by running `sort_word_list` (which will be available in
+the python virtual environment). This is also enforced by CI, and can be checked locally by
+running `pytest`. Both of these tools should be run from the top-level of an `ibex_developers_manual`
+git checkout - the directory that contains `pyproject.toml`.
+
+Sphinx is strict about capitalisation; where multiple spellings are valid, the word will
+need to be added to the word list with each of the valid spellings. An exception is all-lowercase entries in the 
+word list - these also allow a variant with an initial capital letter. 
+
+Where a word or product has a preferred stylisation, for example **ActiveMQ** or **LabVIEW**, only that spelling 
+should be added to the word list. Proper nouns should not have uncapitalised variants added to the word list.
 
 ## Admonitions
 

doc/Glossary.md

@@ -2,7 +2,7 @@
 
 ## ACF
 
-**A**ccess **C**ontrol **F**ile.  A file used by the [Gateway](#gateway) which contains rules for access.
+**Access Control File**.  A file used by the [Gateway](#gateway) which contains rules for access.
 
 ## [ActiveMQ](/system_components/ActiveMQ)
 
@@ -46,7 +46,7 @@ A [Channel Access](#channel-access-ca) Server (CAS) that allows [blocks](#block)
 
 ## [CALab](https://www.helmholtz-berlin.de/zentrum/locations/it/software/exsteuer/calab/index_en.html)
 
-**C**hannel **A**ccess **Lab**oratory.  A library which enables [EPICS](#epics) and [LabVIEW](#labview) to communicate with each other.
+**Channel Access Laboratory**.  A library which enables [EPICS](#epics) and [LabVIEW](#labview) to communicate with each other.
 
 ## [Calibration Files](/system_components/configurations/Calibration-Files)
 
@@ -62,7 +62,7 @@ A device, usually a spinning disc of thick metal with a narrow slot, which allow
 
 ## [CLF](https://www.clf.stfc.ac.uk/Pages/home.aspx)
 
-**C**entral **L**aser **F**acility.  A department at RAL that also uses the [EPICS](#epics) control system.
+**Central Laser Facility**.  A department at RAL that also uses the [EPICS](#epics) control system.
 
 ## [Code Chats](processes/meetings/Code-Chats-and-Lightning-Talks)
 
@@ -92,7 +92,7 @@ A Python script to upgrade current configurations to be compatible with new vers
 
 ## [CSS](http://controlsystemstudio.org/)
 
-"**C**ontrol **S**ystem **S**tudio is an [Eclipse](#eclipse)-based collection of tools to monitor and operate large scale control systems, such as the ones in the accelerator community. It's a product of the collaboration between different laboratories and universities."
+"**Control System Studio** is an [Eclipse](#eclipse)-based collection of tools to monitor and operate large scale control systems, such as the ones in the accelerator community. It's a product of the collaboration between different laboratories and universities."
 
 ## [DAE](/specific_iocs/DAE-and-the-ICP)
 
@@ -119,7 +119,7 @@ A software implementation of hardware.  Usually used to help write and test an [
 
 ## EPICS
 
-**E**xperimental **P**hysics and **I**ndustrial **C**ontrol **S**ystem.  A client/server control system using [Channel Access](#channel-access-ca) as its communication protocol, forming a distributed real-time database of machine values ([PVs](#pv)).
+**Experimental Physics and Industrial Control System**.  A client/server control system using [Channel Access](#channel-access-ca) as its communication protocol, forming a distributed real-time database of machine values ([PVs](#pv)).
 It is a collection of software tools collaboratively developed which can be integrated to provide a comprehensive and scalable control system.
 
 ## Field
@@ -142,7 +142,7 @@ While Git takes care of the underlying version control, GitHub is the collaborat
 
 ## GUI
 
-**G**raphical **U**ser **I**nterface.  AKA "[The GUI](Client)" or [IBEX](#ibex) Client.  A program which provides a graphical method of interacting with the [IBEX](#ibex) Server.
+**Graphical User Interface**.  AKA "[The GUI](Client)" or [IBEX](#ibex) Client.  A program which provides a graphical method of interacting with the [IBEX](#ibex) Server.
 
 ## IBEX
 
@@ -156,7 +156,7 @@ Archives [PV](#pv) values using the [CSS Archive Engine](#archive-engine) which
 
 ## IOC
 
-**I**nput**O**utput**C**ontroller.  A process which reads and writes [PVs](#pv).  Often interfaces with hardware (e.g. sample environment equipment) to enable it to be controlled remotely.
+**Input  Output Controller**.  A process which reads and writes [PVs](#pv).  Often interfaces with hardware (e.g. sample environment equipment) to enable it to be controlled remotely.
 
 ## Java
 
@@ -172,11 +172,11 @@ The journal parser is a program that runs as part of the end run processes. It l
 
 ## [LabVIEW](/system_components/LabVIEW)
 
-**Lab**oratory**V**irtual**I**nstrument**E**ngineering**W**orkbench.  A graphical programming language in which the device drivers for [SECI](#seci) are written.
+**Laboratory Virtual Instrument Engineering Workbench**.  A graphical programming language in which the device drivers for [SECI](#seci) are written.
 
 ## [LeWIS](https://github.com/DMSC-Instrument-Data/lewis)
 
-**Le**t's **W**rite **I**ntricate **S**imulators.  A Python framework for producing and running [emulators](#emulator).  See [Emulating-Devices](/iocs/testing/Emulating-Devices) for more information.
+**Let's Write Intricate Simulators**.  A Python framework for producing and running [emulators](#emulator).  See [Emulating-Devices](/iocs/testing/Emulating-Devices) for more information.
 
 ## Macro
 
@@ -198,7 +198,7 @@ A network-based control system.  Some elements of it are used in the [script ser
 
 ## OPI
 
-**Op**erator **I**nterface.  A file used in [CSS](#css) to enable a user to interact with an IOC graphically.
+**Operator Interface**.  A file used in [CSS](#css) to enable a user to interact with an IOC graphically.
 
 ## Perspective
 
@@ -208,7 +208,7 @@ A network-based control system.  Some elements of it are used in the [script ser
 
 ## PV
 
-**P**rocess **V**ariable.  A named piece of data and the primary object of the [Channel Access Protocol](#channel-access-ca), often associated with a piece of equipment (e.g. status, readback, setpoint, parameter).
+**Process Variable**.  A named piece of data and the primary object of the [Channel Access Protocol](#channel-access-ca), often associated with a piece of equipment (e.g. status, readback, setpoint, parameter).
 
 ## PVLIST
 
@@ -228,15 +228,15 @@ The version of [IBEX](#ibex) to be deployed.
 
 ## SECI
 
-**S**ample **E**nvironment **C**ontrol **I**nterface.  The current instrument control system, currently being replaced by IBEX.  Written in C# and incorporating [LabVIEW](#labview) drivers for the sample environment equipment.  If you need access to the SECI user manual, please ask.
+**Sample Environment Control Interface. An old instrument control system, used before IBEX. No longer in use on any instruments. Written in C# and incorporating [LabVIEW](#labview) drivers for the sample environment equipment.
 
 ## Sequencer
 
 An [EPICS](#epics) module to provide support for [SNL](#snl) files.
 
 ## SNL
 
-**S**tate **N**otation **L**anguage.  A "C-like" language to enable [State Machines](#state-machine) to be written which can then be integrated into [IOCs](#ioc).
+**State Notation Language**.  A "C-like" language to enable [State Machines](#state-machine) to be written which can then be integrated into [IOCs](#ioc).
 
 ## Soft Motor
 
@@ -270,7 +270,7 @@ A tool for running [virtual machines](#virtual-machine).
 
 ## VI
 
-**V**irtual **I**nstrument.  A [LabVIEW](#labview) program, usually a device driver for interacting with sample environment equipment.
+**Virtual Instrument**.  A [LabVIEW](#labview) program, usually a device driver for interacting with sample environment equipment.
 
 ## Virtual Machine
 

doc/Providing-Support.md

@@ -161,7 +161,7 @@ There are a number of tips for [trouble shooting](#all_troubleshooting_links) al
   <summary>This network device isn't connecting</summary>
 
   1. If the device has been working on the ISIS network in that specific hall since the start of May 2025 then this is most likely an issue with the device or the port.
-  1. If this is a new to that hall, or to ISIS generally device, or it hasn’t been used since sometime before May 2025, then this may be a network access issue, and it will need some help from the Infrastructure team, the MCR will have a number for them.
+  1. If this is a new to that hall, or to ISIS generally device, or it hasn't been used since sometime before May 2025, then this may be a network access issue, and it will need some help from the Infrastructure team, the MCR will have a number for them.
 
 </details>
 

doc/client/coding/Connecting-a-View-to-a-PV.md

@@ -447,7 +447,7 @@ The getter returns an empty string, but this does not matter - we could wire it
 
 The setter uses the Writable object to write the new value to the IOC via channel access.
 
-Finally we need to edit the View itself to enable it to bind to titleSP. For this we add a text-box called txtNewTitle and set up the binding:
+Finally we need to edit the View itself to enable it to bind to titleSP. For this we add a text-box called `txtNewTitle` and set up the binding:
 ```java
 ...
 bindingContext.bindValue(WidgetProperties.text(SWT.Modify).observe(txtNewTitle), BeanProperties.value("titleSP").observe(org.csstudio.isis.title.Title.getInstance().model()));

doc/client/coding/GUI-Coding-Conventions.md

@@ -102,7 +102,7 @@ Checkstyle has a suppress warning flag that tells it to ignore certain warning;
 
 * Magic numbers - if it is related to a GUI layout then suppress them.
 
-* Name must match pattern - ignore GUI names that don't match the recommended pattern (e.g. gd_switchToCombo)
+* Name must match pattern - ignore GUI names that don't match the recommended pattern (e.g. `gd_switchToCombo`)
 
 Suppression example:
 

doc/client/coding/Static-analysis.md

@@ -10,7 +10,7 @@ Checkstyle is designed to enforce a set of highly configurable coding standards.
 
 The style rules imposed by Checkstyle are very demanding and it may be helpful to consider them as guidelines rather than as hard rules. At our first analysis of the Eclipse GUI project, Checkstyle showed over 30000 errors and it probably isn't worth the effort to fix all of these. However moving forward, when writing new code, it is a good idea to make at least some effort to conform to the Checkstyle 'rules'.
 
-Checkstyle configuration is done by XML file called 'checkstyle.xml' which is located in the tycho parent directory. This is then set up as a global rule set called IBEX Checks. The rule set used is the default Sun ruleset with some rules disabled (by commenting them out in the XML file). In order to reduce the number of needless Checkstyle warnings, the following specific rules, which are enabled by default, have been disabled for Jenkins:
+Checkstyle configuration is done by XML file called 'checkstyle.xml' which is located in the Tycho parent directory. This is then set up as a global rule set called IBEX Checks. The rule set used is the default Sun ruleset with some rules disabled (by commenting them out in the XML file). In order to reduce the number of needless Checkstyle warnings, the following specific rules, which are enabled by default, have been disabled for Jenkins:
 
 * FileTabCharacterCheck - using a tab character anywhere in the code
 * RegexpSinglelineCheck - line has trailing white space
@@ -88,7 +88,7 @@ For both PMD and FindBugs, there are certain rules which, while generally sensib
 
 ## Maven
 
-The tools may be run as part of a maven build by including them as plugins in the project's pom.xml. In the case of the Eclipse GUI, each plugin is included in the 'tycho.parent' pom.xml file, and is therefore used in every other project (Eclipse plugin) during the build.
+The tools may be run as part of a maven build by including them as plugins in the project's pom.xml. In the case of the Eclipse GUI, each plugin is included in the `tycho.parent` pom.xml file, and is therefore used in every other project (Eclipse plugin) during the build.
 
 * [FindBugs maven plugin](https://gleclaire.github.io/findbugs-maven-plugin/index.html)
 * [CheckStyle maven plugin](http://maven.apache.org/plugins/maven-checkstyle-plugin/)

doc/client/design_docs/Opening-an-OPI-Outside-of-a-Synoptic.md

@@ -2,7 +2,7 @@
 
 ## Names
 
-The suggested name for this is 'Device Screens'. We will change the terminolgy currently used in the synoptic from 'Component' to 'Device' too, for consistency (this avoids ambiguity with a component as part of a configuration).
+The suggested name for this is 'Device Screens'. We will change the terminology currently used in the synoptic from 'Component' to 'Device' too, for consistency (this avoids ambiguity with a component as part of a configuration).
 
 Other ideas for names were:
 * Component Viewer

doc/client/eclipse/Checkstyle-setup.md

@@ -23,8 +23,8 @@ You may need to install an older version to be compatible with our checkstyle co
     1. `Additional Properties` button
         1. `Add...` button
         1. Set:
-            - Name: checkstyle.suppressions.file
-            - Value: C:\Instrument\Dev\ibex_gui\base\uk.ac.stfc.isis.ibex.client.tycho.parent\suppressions.xml
+            - Name: `checkstyle.suppressions.file`
+            - Value: `C:\Instrument\Dev\ibex_gui\base\uk.ac.stfc.isis.ibex.client.tycho.parent\suppressions.xml`
 1. Apply and close: you should now be setup
     1. If you have issues with the highlight colour on a dark theme you can go to: Window -> Preferences, General -> Editors -> Text Editors -> Annotations to change it.