Help System

Help files are *.rst files with reStructuredText markup as described at http://www.sphinx-doc.org/en/stable/rest.html.

The top-level repository for help files is phoebus-doc (https://github.com/kasemir/phoebus-doc) and a snapshotData of the current version is accessible on http://phoebus-doc.readthedocs.io.

The top-level help repository provides the overall structure and content that describes the Phoebus-based CS-Studio in general. Each phoebus application can contribute help content that describes the specific application in more detail. This is done by adding a doc/ folder with an index.rst file to the application sources. When phoebus-doc is built, it includes all phoebus/**/doc/index.rst in the Applications section of the manual. While the *.rst markup is ultimately converted into HTML, some applications might have already have HTML content generated by other means, for example from Javadoc. Any doc/html folder found in the applications source code is copied into the file html folder. To appear in the manual, it needs to be linked from the index.rst of an application via raw tags. For an example, refer to the display builder editor help.

Overall, the help content is thus generated from a combination of

  1. Top-level content defined in phoebus-doc/source/*.rst

  2. Application specific help copied from the phoebus/**/doc/index.rst source tree

  3. Pre-generated HTML folders copied from the phoebus/**/doc/html source tree

In addition to building the help files locally as described below, or viewing a snapshotData of the current version online under the link mentioned above, the help content is also bundled into the phoebus-based CS-Studio product. When the phoebus product is built, it checks for the HTML version of the manual in phoebus-doc/build/html. If found, it is bundled into the product.

Complete build steps of manual and product:

# Obtain sources for documentation and product
git clone https://github.com/kasemir/phoebus-doc.git
git clone https://github.com/shroffk/phoebus.git

# Some application code may contain html content
# that needs to be generated, for example from Javadoc
( cd phoebus/app/display/editor;  ant -f javadoc.xml clean all )

# Building the manual will locate and include
# all ../phoebus/applications/**/doc/index.rst
( cd phoebus-doc; make clean html )
# Windows: Use make.bat html

# Fetch dependencies
( cd phoebus/dependencies; mvn clean install )

# Build the product, which bundles help from
# ../phoebus-doc/build/html
# as phoebus-product/target/doc
( cd phoebus; ant clean dist )

# Could now run the product
( cd phoebus/phoebus-product; sh phoebus.sh )

# or distribute the ZIP file,
# phoebus/phoebus-product/target/phoebus-0.0.1.zip

Internals

In phoebus-doc/source/conf.py, the createAppIndex() method checks for the phoebus sources and builds the application section of the manual.

When invoking the Phoebus Help menu, it looks for a doc/ folder in the installation location (see Locations).

As a fallback for development in the IDE, it looks for phoebus-doc/build/html.