Document Phoebus preferences in Markdown

app/3d-viewer/src/main/resources/3d_viewer_preferences.properties

@@ -9,9 +9,11 @@ read_timeout=10000
 default_dir=$(user.home)
 
 # Cone is approximated with these many faces.
-# 3: Triangular base, most minimalistic
-# 8: Looks pretty good
-# Higher: Approaches circular base,
-# but adds CPU & memory usage
-# and doesn't really look much better
-cone_faces=8
+#
+# :3: Triangular base, most minimalistic
+# :8: Looks pretty good
+# :higher:
+#   Approaches circular base,
+#   but adds CPU & memory usage
+#   and doesn't really look much better
+cone_faces=8

app/alarm/audio-annunciator/src/main/resources/audio_annunciator_preferences.properties

@@ -3,21 +3,29 @@
 # ----------------------------------------
 
 # The audio annunciator will play the audio files specified for the associated alarm severity levels.
-# Currently supported formats are AIFF and WAV files.
-# examples of audio file URL's, they can be local or remote files.
+#
+# Currently supported formats are AIFF and WAV files,
+# which can be local or remote.
+#
+# ```{code-block}
+# :caption: Examples
+#
 # file:/C:/tmp/audio/AudioFileWithWavFormat.wav
 # https://wavlist.com/wav/brass1.wav
+# ```
 
-# default alarm sound, if we don't want severity specific sounds only setting this one preference is enough
+# Default alarm sound.
+#
+# If we don't want severity specific sounds only setting this one preference is enough.
 alarm_sound_url=
 
 minor_alarm_sound_url=
 major_alarm_sound_url=
 invalid_alarm_sound_url=
 undefined_alarm_sound_url=
 
-# audio clip volume (0-100)
+# Audio clip volume (0-100).
 volume=100
 
-# max alarm Duration in seconds.
-max_alarm_duration=10
+# Max alarm Duration in seconds.
+max_alarm_duration=10

app/alarm/logging-ui/src/main/resources/alarm_logging_preferences.properties

@@ -2,7 +2,11 @@
 # Package org.phoebus.applications.alarm.logging.ui
 # -------------------------------------------------
 
-# The URL of the REST API exposed by the alarm logger service (not the elasticsearch port as it was prior to Phoebus 4.0)
+# The URL of the REST API exposed by the alarm logger service.
+#
+# :::{versionchanged} 4.0
+# Prior to the 4.0 release, this was the elasticsearch port.
+# :::
 service_uri = http://localhost:9000
 
 results_max_size = 10000

app/alarm/model/src/main/resources/alarm_preferences.properties

@@ -9,13 +9,16 @@ server=localhost:9092
 kafka_properties=
 
 # Name of alarm tree root.
+#
 # Configures the alarm configuration used by the alarm server.
 # For the UI, it sets the default alarm configuration.
 config_name=Accelerator
 
 # Names of selectable alarm configurations for UI.
-# The `config_name` will be used as the default for newly opened tools,
-# and if `config_names` is empty, it remains the only option.
+#
+# The {prefs:pref}`config_name` will be used as the default for newly opened tools,
+# and if {prefs:pref}`config_names` is empty, it remains the only option.
+#
 # When one or more comma-separated configurations are listed,
 # the UI shows the selected name and allows switching
 # between them.
@@ -27,45 +30,59 @@ connection_timeout=30
 # Timeout in seconds for "sevrpv:" updates
 severity_pv_timeout=5
 
-## Area Panel 
+# :::{rubric} Area Panel
+# :::
 
 # Item level for alarm area view:
-# 1 - Root element
-# 2 - Top-level "area" elements just below root
-# 3 - Show all the items at level 3
+#
+# :1: Root element
+# :2: Top-level "area" elements just below root
+# :3: Show all the items at level 3
 alarm_area_level=2
 
-# Number of columns in the alarm area view
+# Number of columns in the alarm area view.
 alarm_area_column_count=3
 
-# Gap between alarm area panel items
+# Gap between alarm area panel items.
 alarm_area_gap=5
 
-# Font size for the alarm area view
+# Font size for the alarm area view.
 alarm_area_font_size=15
 
 # Limit for the number of context menu items.
+#
 # Separately applied to the number of 'guidance',
-# 'display' and 'command' menu entries. 
+# 'display' and 'command' menu entries.
 alarm_menu_max_items=10
 
-# Initial Alarm Tree UI update delay [ms]
+# Initial Alarm Tree UI update delay, in milliseconds.
 #
 # The initial flurry of alarm tree updates can be slow
 # to render. By allowing the alarm client to accumulate
 # alarm tree information for a little time and then
 # performing an initial bulk representation, the overall
 # alarm tree startup can be faster, especially when
-# the UI is viewed via a remote desktop
+# the UI is viewed via a remote desktop.
 #
-# Set to 0 for original implementation where
+# Set to `0` for original implementation where
 # all alarm tree items are added to the model
 # as they are received in initial flurry of updates.
 alarm_tree_startup_ms=2000
 
-# Order of columns in alarm table
+# Order of columns in alarm table.
+#
 # Allows re-ordering as well as omitting columns
-# The supported columns are: Icon, PV, Description, Alarm Severity, Alarm Message, Alarm Time, Alarm Value, PV Severity, PV Message
+#
+# The supported columns are:
+# - `Icon`
+# - `PV`
+# - `Description`
+# - `Alarm Severity`
+# - `Alarm Message`
+# - `Alarm Time`
+# - `Alarm Value`
+# - `PV Severity`
+# - `PV Message`
 alarm_table_columns=Icon, PV, Description, Alarm Severity, Alarm Message, Alarm Time, Alarm Value, PV Severity, PV Message
 
 # By default, the alarm table uses the common alarm severity colors
@@ -77,70 +94,86 @@ alarm_table_columns=Icon, PV, Description, Alarm Severity, Alarm Message, Alarm
 # based on brightness.
 alarm_table_color_legacy_background=true
 
-# Alarm table row limit
+# Alarm table row limit.
+#
 # If there are more rows, they're suppressed
 alarm_table_max_rows=2500
 
-# Directory used for executing commands
-# May use Java system properties like this: $(prop_name)
+# Directory used for executing commands.
+#
+# May use Java system properties like this: `$(prop_name)`
 command_directory=$(user.home)
 
-# The threshold of messages that must accumulate before the annunciator begins to simply state: "There are X Alarm messages."
+# The threshold of messages that must accumulate before the annunciator begins to simply state:
+# "There are X Alarm messages."
 annunciator_threshold=3
 
-# The number of messages the annunciator will retain before popping messages off the front of the message queue.
+# The number of messages the annunciator will retain
+# before popping messages off the front of the message queue.
 annunciator_retention_count=100
 
 # Timeout in seconds at which server sends idle state updates
 # for the 'root' element if there's no real traffic.
+#
 # Client will wait 3 times this long and then declare a timeout.
 idle_timeout=10
 
-# Name of the sender, the 'from' field of automated email actions 
+# Name of the sender, the 'from' field of automated email actions.
 automated_email_sender=Alarm Notifier <alarm_server@example.org>
 
-# Comma-separated list of automated actions on which to follow up
-# Options include mailto:, cmd:
+# Comma-separated list of automated actions on which to follow up.
+#
+# Options include `mailto:`, `cmd:`
 automated_action_followup=mailto:, cmd:, infopv:
 
-# Optional heartbeat PV
+# Optional heartbeat PV.
+#
 # When defined, alarm server will set it to 1 every heartbeat_secs
-#heartbeat_pv=Demo:AlarmServerHeartbeat
+#
+# ```{code-block} properties
+# :caption: Example
+#
+# heartbeat_pv=Demo:AlarmServerHeartbeat
+# ```
 heartbeat_pv=
 
-# Heartbeat PV period in seconds
+# Heartbeat PV period in seconds.
 heartbeat_secs=10
 
-# Period for repeated annunciation
+# Period for repeated annunciation.
+#
+# If there are active alarms, i.e. alarms that have not been acknowledged,
+# a message "There are 47 active alarms" will be issued.
 #
-# If there are active alarms, i.e. alarms that have not been acknowleded,
-# a message "There are 47 active alarms" will be issued
+# :format: `HH:MM:SS`, for example `00:15:00` to nag every 15 minutes.
 #
-# Format is HH:MM:SS, for example 00:15:00 to nag every 15 minutes.
-# Set to 0 to disable  
+# Set to 0 to disable
 nag_period=00:15:00
 
-# Connection validation period in seconds
+# Connection validation period in seconds.
 #
 # Server will check the Kafka connection at this period.
 # After re-establishing the connection, it will
 # re-send the state of every alarm tree item.
+#
 # Set to 0 to disable.
 connection_check_secs=5
 
-# To turn on disable notifications feature, set the value to true
+# To turn on disable notifications feature, set the value to `true`
 disable_notify_visible=false
 
-# Options for the "Disable until.." shortcuts in the PV config dialog
+# Options for the "Disable until.." shortcuts in the PV config dialog.
+#
+# :format:
+#   comma separated, each option needs to comply with `TimeParser.parseTemporalAmount()`:
 #
-# Comma separated, each option needs to comply with TimeParser.parseTemporalAmount():
-# 30 seconds, 5 minutes, 1 hour, 6 hours, 1 day, 30 days, ...
+#   30 seconds, 5 minutes, 1 hour, 6 hours, 1 day, 30 days, ...
 shelving_options=1 hour, 6 hours, 12 hours, 1 day, 7 days, 30 days
 
 # Macros for UI display, command or web links
 #
-# Format: M1=Value1, M2=Value2
+# :format: `M1=Value1, M2=Value2`
 macros=TOP=/home/controls/displays,WEBROOT=http://localhost/controls/displays
 
-# Max time in ms a producer call will block.
+# Max time in milliseconds a producer call will block.
 max_block_ms=10000

app/channel/views/src/main/resources/cv_preferences.properties

@@ -2,5 +2,5 @@
 # Package org.phoebus.channel.views.ui
 # --------------------------------------
 
-# Show the active PVs only 
+# Show the active PVs only?
 show_active_cb=false

app/console/src/main/resources/console_preferences.properties

@@ -3,34 +3,43 @@
 # ----------------------------------------
 
 # Number of output lines to keep.
+#
 # Older output is dropped.
 output_line_limit=100
 
 # Number of lines to keep in input history,
+#
 # accessible via up/down cursor keys
 history_size=20
 
-# Font name and size
+# Font name.
 font_name=Liberation Mono
+
+# Font size.
 font_size=14
 
-# Prompt (may include trailing space)
+# Prompt.
+#
+# May include trailing space.
 prompt=>>>\ 
 
-# Prompt (input field) info
+# Prompt (input field) info.
 prompt_info=Enter console command
 
 # 'Shell' to execute.
 #
-# Examples:
-#   /usr/bin/python -i
-#   /usr/bin/python -i /path/to/some/initial_file.py
-#   /bin/bash
+# ```{code-block}
+# :caption: Examples
+#
+# /usr/bin/python -i
+# /usr/bin/python -i /path/to/some/initial_file.py
+# /bin/bash
+# ```
 #
 # Value may include properties.
 shell=/usr/bin/python -i
 
-# Folder where the shell process should be started
+# Folder where the shell process should be started.
 #
 # Value may include properties.
-directory=$(user.home)
+directory=$(user.home)

app/databrowser-json/src/main/resources/archive_reader_json_preferences.properties

@@ -3,7 +3,7 @@
 # ---------------------------------------
 
 # Shall a precision of zero for a floating-point value result in this value
-# using a number format without fractional digits (true) or shall it be treated
+# using a number format without fractional digits (`true`) or shall it be treated
 # as an indication that the value should be rendered with a default number of
-# fractional digits (false)?
+# fractional digits (`false`)?
 honor_zero_precision=true

app/databrowser-timescale/src/main/resources/archive_ts_preferences.properties

@@ -2,21 +2,26 @@
 # Package org.csstudio.archive.ts
 # -------------------------------
 
-# User and password for reading archived data
+# User for reading archived data
 user=report
+# Password for reading archived data
 password=$report
 
-# Timeout [seconds] for certain SQL queries, 0 to disable timeout.
+# Timeout in seconds for certain SQL queries, 0 to disable timeout.
+#
 # Fundamentally, the SQL queries for data take as long as they take
 # and any artificial timeout just breaks queries that would otherwise
 # have returned OK a few seconds after the timeout.
+#
 # A timeout is used for operations other than getting the actual data,
 # for example the channel id-by-name query which _should_ return within
 # a short time.
 timeout_secs=120
 
 # JDBC Statement 'fetch size':
+#
 # Number of samples to read in one network transfer.
+#
 # Speed tends to increase with fetch size.
-# On the other hand, bigger numbers can result in java.lang.OutOfMemoryError.
-fetch_size=10000
+# On the other hand, bigger numbers can result in `java.lang.OutOfMemoryError`.
+fetch_size=10000