Merge pull request #3623 from ControlSystemStudio/markdown-properties-docs

Markdown properties docs

Author: shroffk

.gitignore

@@ -125,3 +125,9 @@ phoebus-product/settings_template.ini
 docs/source/applications.rst
 docs/source/services.rst
 
+# Ignore Sphinx extensions and build artifacts
+docs/source/_ext/**/__pycache__/
+docs/source/_ext/**/*.pyc
+
+# Ignore pip installation metadata
+docs/phoebus_docs.egg-info/

.readthedocs.yaml

@@ -8,8 +8,11 @@ build:
 # Build from the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
+  builder: html
+  fail_on_warning: false
 
-# Explicitly set the version of Python and its requirements
+# Install Python dependencies from pyproject.toml in docs/
 python:
   install:
-    - requirements: docs/source/requirements.txt
+    - method: pip
+      path: docs

docs/README.md

@@ -3,28 +3,53 @@ Phoebus Documentation
 
 Documentation for https://github.com/ControlSystemStudio/phoebus
 
-View latest snapshotData at https://control-system-studio.readthedocs.io
+View latest snapshot at https://control-system-studio.readthedocs.io
 
-You can build a local copy using a local installation of sphinx or with maven
+You can build a local copy using Pixi or a local installation of sphinx.
 
-Option 1.
-You need to install sphinx
-```
-   # Standard way
-   pip install Sphinx
+## Option 1: Using Pixi (Recommended)
 
-   # Some RedHat setups
-   sudo yum install python-sphinx
-```
+Install [Pixi](https://pixi.sh) and run:
 
-Then build the web version:
+```bash
+# Navigate to the docs directory
+cd docs
+
+# Build the documentation
+pixi run build
+
+# Or directly build HTML
+pixi run html
+
+# Serve documentation locally
+pixi run serve
+
+# Clean build artifacts
+pixi run clean
 ```
-   make clean html
+
+The Pixi configuration is in `pyproject.toml` under the `[tool.pixi.*]` sections.
+
+## Option 2: Using Sphinx directly
+
+You need to install sphinx and its dependencies:
+
+```bash
+# Navigate to the docs directory
+cd docs
+
+# Install from pyproject.toml (installs all dependencies)
+pip install .
 ```
 
-Option 2.
+Alternatively, on some RedHat setups:
+```bash
+sudo yum install python-sphinx
 ```
-   mvn verify -P sphinx -N
+
+Then build the web version:
+```bash
+make clean html
 ```
 
 The above creates a document tree starting with `build/html/index.html`.
@@ -43,7 +68,7 @@ git clone https://github.com/ControlSystemStudio/phoebus.git
 ( cd phoebus/doc; make clean html )
 ```
 
-When then building the Phoebus UI product, it will incude the document tree
+When then building the Phoebus UI product, it will include the document tree
 as online help accessible via the `Help` menu.
 
 
@@ -68,7 +93,7 @@ Documentation Components
 
    Additionally, the folders are also checked for `doc/images/` folders.
    Resources used by the `index.rst` files should be places in this folder to 
-   ensure they are available to sphinx to generate the documenation.
+   ensure they are available to sphinx to generate the documentation.
 
 3) Preference Descriptions
 
@@ -93,7 +118,7 @@ Documentation Components
 4) Plain HTML
 
    The content of all `../phoebus/**/doc/html` folders is copied into the
-   henerated html output directory tree.
+   generated html output directory tree.
 
    This allows including existing HTML content "as is".
    An `index.rst` file in the corresponding phoebus module may then refer
@@ -114,6 +139,3 @@ Documentation Components
 
 For technical details on how the document components are assembled,
 check `createAppIndex()` and `createPreferenceAppendix()` in `source/conf.py`.
-
-
-

docs/pixi.lock

@@ -0,0 +1,33 @@
+[project]
+name = "phoebus-docs"
+version = "0.1.0"
+description = "Phoebus documentation build environment"
+requires-python = ">=3.9"
+dependencies = [
+    "sphinx>=8.2",
+    "sphinx_rtd_theme>=3.0",
+    "myst-parser>=4.0",
+    "setuptools",
+]
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
+
+[tool.pixi.dependencies]
+python = ">=3.9"
+
+[tool.pixi.pypi-dependencies]
+phoebus-docs = { path = ".", editable = true }
+
+[tool.pixi.tasks]
+clean = "sphinx-build -M clean source build"
+html = "sphinx-build -M html source build"
+build = { depends-on = ["html"] }
+serve = "python -m http.server 8000 --directory build/html"
+
+[tool.pixi.feature.dev.dependencies]
+sphinx-autobuild = "*"
+
+[tool.pixi.environments]
+dev = ["dev"]

docs/pyproject.toml

@@ -1,5 +1,6 @@
 """Fetching properties files, parsing, and storing them."""
 
+import os
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
@@ -113,14 +114,15 @@ def parse_all_properties_files(_app: Sphinx, config: Config):
 
     files: list[tuple[Path, str]] = []
 
-    for dirpath, _dirnames, filenames in root.walk():
+    for dirpath, _dirnames, filenames in os.walk(root):
+        dirpath_obj = Path(dirpath)
         # Skip build directories
-        if "target" in dirpath.parts:
+        if "target" in dirpath_obj.parts:
             continue
 
         for filename in filenames:
             if filename.endswith("preferences.properties"):
-                file = dirpath / filename
+                file = dirpath_obj / filename
                 pack = package_name(file) or filename
                 _DATA[pack] = _parse_preferences_file(file, pack, root)
 

docs/source/_ext/preferences_listing/_parsing.py

@@ -42,7 +42,7 @@ Exemples :
 **-main org.csstudio.display.builder.model.AdvancedConverter  input/path/to/folder**
 
 Converter application
------------------
+----------------------
 
 Located in *Utility -> OPI converter*, it will generate a pop up window. In this pop up, you can choose a input file or folder with the Browse button in the input section. In a similar way, you can choose or not a output folder.
 To run the conversion you need to press the run button. 
@@ -61,9 +61,3 @@ If you select **YES**, it will **delete** all bob files present in the output fo
 If you select **NO**, you return in the browsing section.
 
 During the conversion, you can follow the conversion process with the progress bar. When the conversion is done, you return in the browsing section and can close the window with the "x" button or rerun a conversion.
-
-
-
-
-
-

docs/source/converter.rst

@@ -1,64 +1,58 @@
-=================
-AdvancedConvertor
-=================
-
-OPI to BOB convertor
---------------------
-
-
-Table:
-
-+ Description
-+ Command Line
-+ Converter application
-
-Description
-------------
-
-AdvancedConverter is a tool to convert massively and recursively CSS OPI to Phoebus BOB files. It will automatically convert the widgets and their properties from the legacy file format.
-
-The converter takes folder or files and convert any OPI files into a BOB files (without delete previous OPI files).
-The programm keep the hierarchy, subfolders, scrypt and files inside. 
-
-Command Line
-------------
-To use this AdvancedConvertor, you can do it via this command line invocation:
-
-Usage: Usage: -main org.csstudio.display.builder.model.AdvancedConverter [-help] [-output /path/to/folder] </path/to/opi/folder>
-
-Converts BOY "*".opi files to Display Builder "*".bob format
-
-**-output** /path/to/folder   - Folder into which converted files are written
-
-<files>                   - One or more files to convert
-
-Exemples : 
- *Convert and copy in another folder*
-
-**-main org.csstudio.display.builder.model.AdvancedConverter** *-output* **output/path/to/folder input/path/to/folder**
-
-*Convert and stay in the folder*
-
-**-main org.csstudio.display.builder.model.AdvancedConverter  input/path/to/folder**
-
-Converter application
------------------
-
-Located in *Utility -> OPI converter*, it will generate a pop up window. In this pop up, you can choose a input file or folder with the Browse button in the input section. In a similar way, you can choose or not a output folder.
-To run the conversion you need to press the run button. 
-
-If the output is empty, the conversion will be done in the input folder.
-
-Right before the conversion, you might have an overriding message window. It appear when you already converted a file in the output folder.
-
-If you select **YES**, it will **delete** all bob files present in the output folder and process the conversion normaly and convert evey opi files. 
-
-If you select **NO**, you return in the browsing section.
-
-During the conversion, you can follow the conversion process with the progress bar. When the conversion is done, you return in the browsing section and can close the window with the "x" button or rerun a conversion.
-
-
-
-
-
-
+=================
+AdvancedConvertor
+=================
+
+OPI to BOB convertor
+--------------------
+
+
+Table:
+
++ Description
++ Command Line
++ Converter application
+
+Description
+------------
+
+AdvancedConverter is a tool to convert massively and recursively CSS OPI to Phoebus BOB files. It will automatically convert the widgets and their properties from the legacy file format.
+
+The converter takes folder or files and convert any OPI files into a BOB files (without delete previous OPI files).
+The programm keep the hierarchy, subfolders, scrypt and files inside. 
+
+Command Line
+------------
+To use this AdvancedConvertor, you can do it via this command line invocation:
+
+Usage: Usage: -main org.csstudio.display.builder.model.AdvancedConverter [-help] [-output /path/to/folder] </path/to/opi/folder>
+
+Converts BOY "*".opi files to Display Builder "*".bob format
+
+**-output** /path/to/folder   - Folder into which converted files are written
+
+<files>                   - One or more files to convert
+
+Exemples : 
+ *Convert and copy in another folder*
+
+**-main org.csstudio.display.builder.model.AdvancedConverter** *-output* **output/path/to/folder input/path/to/folder**
+
+*Convert and stay in the folder*
+
+**-main org.csstudio.display.builder.model.AdvancedConverter  input/path/to/folder**
+
+Converter application
+----------------------
+
+Located in *Utility -> OPI converter*, it will generate a pop up window. In this pop up, you can choose a input file or folder with the Browse button in the input section. In a similar way, you can choose or not a output folder.
+To run the conversion you need to press the run button. 
+
+If the output is empty, the conversion will be done in the input folder.
+
+Right before the conversion, you might have an overriding message window. It appear when you already converted a file in the output folder.
+
+If you select **YES**, it will **delete** all bob files present in the output folder and process the conversion normaly and convert evey opi files. 
+
+If you select **NO**, you return in the browsing section.
+
+During the conversion, you can follow the conversion process with the progress bar. When the conversion is done, you return in the browsing section and can close the window with the "x" button or rerun a conversion.