Script your Documentation

Note

Please install the CODESYS Library Documentation Support package. Without the installation of this extension it is not possible to use the possibilities of the CODESYS LibDoc Scripting Collection.

The term DocScripting describes the work flow which is necessary for creating a full documentation in various formats from a CODESYS library and the comments which are embedded in this library.

It should be possible to distribute a Library with the aid of the Package Manager to end customers. The Package contains the library in the “*.compiled-library” format (see Deployment), as well as a “*.chm”-file for the related online help, in which the documentation for the library is assembled. The Package Manager installs these parts of the package in a way that the library can be included by the customer in his projects (“Add Library”) and that the context-sensitive help (accessible via F1 key in a CODESYS editor) can find the matching page in the library-related online help.

The source of documentation is a CODESYS library, which contains comments for the respective library parts. The concerned elements are described in section Documentation Areas. By a so-called DocExport the desired parts of the CODESYS library get exported to a JSON-file.

Note

The DocExport is only intended for providing CODESYS project parts as JSON-files, which are needed for the further steps in the documentation process. It cannot be used to create project elements in CODESYS by an import. For this need however you could use the PLCopenXML export-/import commands.

The following elements can be transferred for documentation purposes from a CODEYS library to a JSON-file by using the DocExport command:

  • Project Information

  • Project Structure

  • Library Manager

  • Program Organisation Units

  • Data Unit Types

  • Global Variable Lists

  • Interfaces

  • ST-Code Implementation

  • Visualization Objects

  • Texlists

  • Application Composer Moduls

  • Image Pools

Note

The Command DocExport is in implemented with CODESYS V3.5 SP5.

It is not recommended to copy the concrete texts from the source text elements (Content) and the comments of a CODESYS project directly to a frame document (Frame). It should be possible to adapt the document structure, which is created by the script (Generate), independently from the project structure to the specific ideas of the technical writer. The source texts and comments in the CODESYS project and the enclosing texts in the frame document should be developed independently of each other. So it is necessary to merge the texts of the frame document and the source texts and comments from the CODESYS project at a late as possible point in time (Source), namely just before the time of generation the final formatting of the whole project documentation.

Note

Due to the fact that the scripting Collection is now part of the CODESYS Library Documentation Support package, it is no longer absolutely necessary to install additional tools [1].

Note

By design, CODESYS installs the Scripting Collection into a directory with a name consistent with the version number, e.g. CODESYS\\DocScripting\\3.5.5.0\libdoc.exe, so that you can have multiple versions of the CODESYS Scripting Collection on the same system without conflicts. CODESYS tries not automatically to modify the PATH environment variable, so that you always have control over which copy of the CODESYS Scripting Collection is your favourite one.

Typing the full path name for a the libdoc.exe each time may get tedious, so add the directory for your default libdoc.exe version to the PATH. Assuming that your libdoc.exe installation is in C:\Program Files (x86)\3S CODESYS\CODESYS\DocScripting\3.5.5.0, add this to your PATH.

The CODESYS LibDoc Scripting Collection is accessible with a wrapper called libdoc.
After running the CODESYS setup we can call the script:
> libdoc --help

This command line should result in the following display:

CODESYS LibDoc Scripting Collection V3.5.11.0

Usage:
    libdoc -h | --help | --version
    libdoc export [<library> [<content>]]
    libdoc clean [<original-content> [<cleaned-content>]]
    libdoc generate [-f] [-b] [-c] [-s | --slug=<maxch>] [<content> [<frame>]]
    libdoc merge [-d] [<content> [<frame> [<source>]]]
    libdoc transform (chm|html|json|latex|lmd|pdf|pot|xml) [[<struct>] [<language>]]
    libdoc make [-n] [<input> [<output>]]
    libdoc fresh [<frame>]

Options:
    -h --help       Show this screen.
    --version       Show version.
    -s              Slugify (ensure readable) names for file names. The length of the name stems is limited to 16.
    --slug=<maxch>  Specify maximal length for slugified file name stems.
    <library>       The CODESYS library.
    <content>       JSON serialized content of a CODESYS library.
    <frame>         Folder structure which mimics the structure of the library.
    <source>        The project folder for the sphinx-doc package.
    <struct>        One of the following structures: <frame> or <source>
    <language>      The code for the language in which the documentation will be localized.
    <input>         A file of one of the following types library, json
    <output>        A file or a folder of one of the following types chm, lmd, html

Commands:
    export          Using CODESYS and its DocExport functionality to serialize the <content> in a JSON file.
                    This command needs a CODESYS installation.

    clean           Analyses the <original-content> and generates a cleaned version named <cleaned-content>.
                    The default behaviour is defined as follows:
                    * Elements marked with the attributes ``hide`` and ``conditionalshow`` will be removed.
                    * Elements with the modifiers ``INTERNAL`` and ``PRIVATE`` will be removed.
                    * All other Elements will not be removed.
                    This default behaviour can be adapted individually by providing a customized ``clean.conf`` file.

    generate        Parse the library <content> and generates/updates the <frame> folder structure which mimics
                    the structure of the library.
                    The option '-f' forces overwriting existing files!
                    The option '-b' generates a *.bak file before overwriting an existing file.
                    The option '-c' generates condensed paths inside the <frame> (Only one folder level).
                    The options '-s' and '--slug' generates slugified filenames inside the <frame>.
                    The later allows to specify the maximal number of character of file name stem.
                    Both options work only together with '-c' option.
                    Note: The file 'conf.py' will never be overwritten.

    merge           Replaces the placeholders in the <frame> structure and  generates/updates
                    a sphinx-doc project structure <source>. (The option '-d' displays the merge cache for debugging)

    transform       Using the sphinx-doc package to transform the <source> structure in a distributable
                    document in chm, html, json, latex, lmd, pdf, pot or xml format.
                    This command needs for generating a chm-file the installation of the Microsoft HTML-Workshop software.
                    The following formats are available:
                    chm:   Transforms the content of <source> to a compiled Microsoft HTML Help document.
                    html:  Transforms the content of <source> to a collection of static html pages.
                    json:  Transforms the content of <source> to a directory with JSON files.
                    latex: Transforms the content of <source> to a bunch of LaTeX files, basis for pdf transformation.
                    lmd:   Transforms the content of <source> to a CODESYS compatible library manager documentation element.
                    pdf:   Transforms the content of <source> to a document in pdf format.
                    pot:   Transforms the content of <source> to a gettext-style message catalog, basis for localisation.
                    xml:   Transforms the content of <source> to the Docutils native XML files.

    make            Tries to generate the <output> from the defined <input>.
                    The option '-n' generates normal paths inside the <frame>.
                    Generating condensed paths is the default.
                    Examples:
                    libdoc make lib.library lib.lmd -> Generates a lib.lmd file from lib.library
                    libdoc make lib.json lib.lmd -> Generates a lib.lmd file from lib.json
                    libdoc make lib.library lib.chm -> Generates a lib.chm file from lib.library
                    libdoc make lib.json lib.chm -> Generates a lib.chm file from lib.json
                    libdoc make lib.library html -> Generates a lib-html folder from lib.library
                    libdoc make lib.json html -> Generates a lib-html folder from lib.json
                    libdoc make po-dir xlf-dir -> Convert the po files to XLIFF files
                    libdoc make xlf-dir po-dir -> Convert the XLIFF files to po files
                    libdoc make po-dir -> Convert the po files to mo files

    fresh           Tries to generate a fresh frame documentation folder structure in the current working directory.
                    The parameter <frame> is optional and defaults to "Frame".

See in the following the description of a tool chain, which can meet all the requirements listed in the paragraph above:

_images/DocScripting.png
Export

The Export command generates a JSON-file. This generated JSON-file is called the content. It contains all documentation related parts of a CODESYS library file in a special notation. Every comment and every attribute pragma will transparently exported from the library source code to the JSON-file. This means: The library developer can add these things for controlling the future DocScripting processing. (please take a look to the Clean command.)

The DocExport can be called with the following command line:

> libdoc export SML_Basic.library SML_Basic.json

The resulting display may be:

export <lib> to <content> using <codesys>
<codesys> = "CODESYS.exe" --Profile="CODESYS V3.5 SP5"
<lib> = SML_Basic.library
<content> = SML_Basic.json
calling: "CODESYS.exe" --Profile="CODESYS V3.5 SP5" --noUI --docexport="SML_Basic.library|SML_Basic.json"
...
Result: 0 -- Done!

After executing this command you will find a JSON file as a sibling of the library file.

Note

The export script tries to locate the CODESYS.exe in the file system. This search can only be successful if CODESYS was installed in a default location and with a standard name. It is possible to define a location other than the default location with the definition of a special environment variable named LIBDOC_CODESYS. The value of this variable should follow this specification: "<path to codesys>" --Profile="<codesys profile>"

Example: "C:\Program Files (x86)\Fanta\Common\CODESYS.exe" --Profile="Fanta Development Build"

Generate

This script generates a hierarchy of folders and files representing the first version of what we call the frame document basing on the library structure described in the JSON-file. Each folder in the original CODESYS library will be represented by a chapter in the frame document. The other elements of the CODESYS library (e.g. POU, GVL, DUT, …) get inserted below the respective chapter as subchapters. In doing so, not only the concrete content of the elements will be transferred, but also references (placeholders) back to the particular elements in the JSON file.

This process step enables the programmer to modify contents and comments in the respective library parts, while at the same time the technical writer can create and edit texts in the generated extended document structure, which are not directly depending on the source code of the CODESYS project (e.g. overviews, exercises, background information). So the elements content and frame can be edited at the same time and independently of one another, as long as the references on the each other document do not get destroyed/deleted.

So in the CODESYS project the folder structure (order and hierarchy) can be modified, also new folders can be created on the different levels. Project elements can be changed or repositioned within the folder structure.

In the frame document a completely independent chapter structure (hierarchy, naming, order) can be used. The elements from the CODESYS project can be placed there according to the requirements of the technical editor. The CODESYS project structure and the structure of the documentation are completely independent from one another. Always when the technical editor wants to insert a CODESYS project element at a certain position in the frame document he just has to insert the corresponding reference.

Generating the documentation structure in the Frame directory can be done with the following command line:

> libdoc generate SML_Basic.json Frame

The resulting display may look like this:

Generate: [...] Frame\todo.rst
Generate: [...] Frame\info.rst
Generate: [...] Frame\index.rst
Generate: [...] Frame\DSP402\fld-DSP402.rst
Generate: [...] Frame\DSP402\SML_DSP402_StateMachine.rst
...
Generate: [...] Frame\DSP402\pou-SML_ControlWordBySDO\SetControlWord.rst
Generate: [...] Frame\DSP402\pou-SML_ControlWordBySDO\Init.rst
Generate: [...] Frame\Base\fld-Base.rst
Generate: [...] Frame\Base\Axis_REF_SML.rst
...
Generate: [...] Frame\Base\Error\fld-Error.rst
Generate: [...] Frame\Base\Error\SML_LogFBError.rst
Generate: [...] Frame\Base\Error\SML_ClearFBError.rst
...
Generate: [...] Frame\Base\SML_Constants.rst
Generate: [...] Frame\Base\SML_FBERROR.rst
...
Generate: [...] Frame\Base\Command-handling\Helper-functions\SML_Cmd_SendReached.rst
Generate: [...] Frame\Base\Command-handling\Helper-functions\SML_Cmd_SendError.rst
...
Generate: [...] Frame\PLCopen\fld-PLCopen.rst
Generate: [...] Frame\PLCopen\MC_MoveAbsolute_SML.rst
Generate: [...] Frame\PLCopen\MC_WriteBoolParameter_SML.rst
Generate: [...] Frame\PLCopen\MC_WriteParameter_SML.rst
Generate: [...] Frame\PLCopen\MC_MoveVelocity_SML.rst
Generate: [...] Frame\PLCopen\MC_Power_SML.rst
Generate: [...] Frame\PLCopen\MC_Reset_SML.rst
Generate: [...] Frame\PLCopen\MC_Stop_SML.rst
Generate: [...] Frame\PLCopen\Helpers\fld-Helpers.rst
Generate: [...] Frame\PLCopen\Helpers\SML_MsgSender.rst
...
Generate: [...] Frame\PLCopen\Helpers\SML_LogFBError_TS.rst
Generate: [...] Frame\PLCopen\Helpers\SML_ClearFBError_TS.rst
Generate: [...] Frame\PLCopen\MC_ReadParameter_SML.rst
Generate: [...] Frame\PLCopen\pou-MC_ReadParameter_SML\CallReadParam.rst
Generate: [...] Frame\PLCopen\MC_ReadBoolParameter_SML.rst
Generate: [...] Frame\PLCopen\MC_Home_SML.rst
Generate: [...] Frame\PLCopen\MC_MoveRelative_SML.rst
Generate: [...] Frame\PLCopen\MC_ReadStatus_SML.rst
Generate: [...] Frame\PLCopen\MC_Halt_SML.rst
Generate: [...] Frame\Additional\fld-Additional.rst
Generate: [...] Frame\Additional\SML_ReinitDrive.rst
Generate: [...] Frame\Additional\SML_ChangeAxisConfig.rst
Generate: [...] Frame\Additional\SML_StartupDrive.rst
Generate: [...] Frame\Additional\SML_SetOpmode.rst

After this procedure you should find the whole project structure with its folders and files placed inside the Frame folder.

Merge

In this step the elements content and frame get merged to another set of documents, this we call source. For this purpose all references to the elements in the CODESYS project, found in the frame document set, will get replaced by their current concrete content. The source document set will consist of pure mark-up (reStructuredText), which then can be processed by the Sphinx Script Package without the need of any further CODESYS-specifc treatment.

Transform
The Sphinx Script Package is utilized to transform the set of reStructuredText formated source files into various output formats like CHM or HTML.
Only the transformation to the HTML format is working out of the box.
For the other formats like CHM or PDF, some additional software (see: Tool installation) is needed.

The transformation of the Frame directory to the HTML format can be done with the following command line:

> libdoc transform html Frame

The resulting display may look like this:

Running Sphinx v1.2.1
loading pickled environment... done
building [html]: targets for 206 source files that are out of date
updating environment: 0 added, 206 changed, 0 removed
reading sources... [  0%] Additional/SML_ChangeAxisConfig
reading sources... [  0%] Additional/SML_ReinitDrive
reading sources... [  1%] Additional/SML_SetOpmode
reading sources... [  1%] Additional/SML_StartupDrive
...
reading sources... [ 99%] index
reading sources... [ 99%] info
reading sources... [100%] todo
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  0%] Additional/SML_ChangeAxisConfig
writing output... [  0%] Additional/SML_ReinitDrive
writing output... [  1%] Additional/SML_SetOpmode
writing output... [  1%] Additional/SML_StartupDrive
writing output... [  2%] Additional/fld-Additional
writing output... [  2%] Base/Axis_REF_Base_SML
writing output... [  3%] Base/Axis_REF_SML
...
writing output... [ 99%] index
writing output... [ 99%] info
writing output... [100%] todo

writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 0 warnings.

After this you should find a index.html file inside the Build/Frame/html folder.