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
Top-level content defined in
phoebus-doc/source/*.rst
Application specific help copied from the
phoebus/**/doc/index.rst
source treePre-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
.