docs: create a Sphinx domain extension to document preference settings

[minijackson]

This changes how the preference settings are fetched and put into the documentation.

Instead of creating the preference_properties.rst file in conf.py, this PR creates a Sphinx extension that parses the preference files, and outputs "objects", like Sphinx would do for documenting a Python or a C API.

Some more information can be found here:

• Sphinx' own domains documentation
• "Adding a reference domain" Sphinx tutorial.

This is quite a bit more Python code than the previous implementation, but gives the following benefits:

• A structured, more readable output than code blocks of properties files

• More readable preference descriptions, now that they are with markup

• A more complete table of contents in the side bar

• Referenceable packages and preferences in the documentation,
  by using the new preferences:pack and preferences:pref roles

• If a document references a preference that doesn't exist, the Sphinx build will output a warning. This helps quite a bit keeping the documentation up-to-date.

• "[source]" links to GitHub for viewing the properties file

• Indices of preferences, in the "genindex.html" and
  "preferences-index.html" pages

I've been running something similar to this for EPNix, and I found that once done, there's not much maintenance to do.

I have another PR ready after this one that changes the doc-comments inside properties files so that they have proper markup, but I wanted to propose a PR as small as possible (and it's already quite big).

[georgweiss]

Admit I'm not a Phyton guy, but I get the following (missing Python dependency?):

Original exception:
Traceback (most recent call last):
  File "sphinx/registry.py", line 417, in load_extension
  File "importlib/__init__.py", line 127, in import_module
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/Users/georgweiss/projects/phoebus/docs/source/_ext/preferences_listing/__init__.py", line 10, in <module>
    from sphinx.util.typing import ExtensionMetadata
ImportError: cannot import name 'ExtensionMetadata' from 'sphinx.util.typing' (/var/folders/4_/5qrr1nkn0_957tp3n0ltdn502f2zw4/T/_MEIT7Hipk/sphinx/util/typing.pyc)


Traceback (most recent call last):
  File "sphinx/registry.py", line 417, in load_extension
  File "importlib/__init__.py", line 127, in import_module
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/Users/georgweiss/projects/phoebus/docs/source/_ext/preferences_listing/__init__.py", line 10, in <module>
    from sphinx.util.typing import ExtensionMetadata
ImportError: cannot import name 'ExtensionMetadata' from 'sphinx.util.typing' (/var/folders/4_/5qrr1nkn0_957tp3n0ltdn502f2zw4/T/_MEIT7Hipk/sphinx/util/typing.pyc)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "sphinx/cmd/build.py", line 279, in build_main
  File "sphinx/application.py", line 245, in __init__
  File "sphinx/application.py", line 402, in setup_extension
  File "sphinx/registry.py", line 421, in load_extension
sphinx.errors.ExtensionError: Could not import extension preferences_listing (exception: cannot import name 'ExtensionMetadata' from 'sphinx.util.typing' (/var/folders/4_/5qrr1nkn0_957tp3n0ltdn502f2zw4/T/_MEIT7Hipk/sphinx/util/typing.pyc))

Extension error:
Could not import extension preferences_listing (exception: cannot import name 'ExtensionMetadata' from 'sphinx.util.typing' (/var/folders/4_/5qrr1nkn0_957tp3n0ltdn502f2zw4/T/_MEIT7Hipk/sphinx/util/typing.pyc))
[INFO] Sphinx exited with code 2. Took 16756ms.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  18.147 s
[INFO] Finished at: 2025-09-26T16:48:49+02:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal kr.motd.maven:sphinx-maven-plugin:2.10.0:generate (default) on project parent: Failed to run the report: Sphinx report generation failed -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

[minijackson]

@georgweiss Yes, apparently I developed the extension for a more recent version of Sphinx, so I had to update the Sphinx version in the requirements.txt.

I just pushed it, you might have checked out the PR before that.

But somehow the ReadTheDocs output doesn't show the preferences, and I'm currently trying to fix that too…

[minijackson]

But somehow the ReadTheDocs output doesn't show the preferences, and I'm currently trying to fix that too…

There we go! That was definitely a mistake on my part.

Here's the output if you want to see it: https://control-system-studio--3567.org.readthedocs.build/en/3567/preference_properties.html

[jacomago]

Is it possible to have the source link to a file hosted in the read the docs? I think we host the docs inside of phoebus and we might want an airgapped network.

[minijackson]

@jacomago technically, it should be possible, but I'd argue there is no need: the entirety of the properties file is rendered on the page. I think the [source] link is more useful to developers than Phoebus users.