Different Output Formats for Library Documentation

HTML Output Format

The libdoc transform html <struct> script uses the Sphinx module "StandaloneHTMLBuilder" for generating a discrete hypertext document in a directory structure. This is populated with the files that are required for defining the appearance (JavaScript, CSS, images, and so on). The file conf.py in the Sphinx project provides numerous setting options. Detailed information about these setting are found in the Sphinx documentation for HTML options.

Example of how to effectively call the CODESYS LibDoc Scripting Collection for generating an HTML file:

cd <config-dir>
sphinx-build -b html -c . -d Build\Frame\doctrees -t libdoc_html Frame Build\Frame\html

LMD Output Format

The special requirements on the structure of the library documentation for the library manager in CODESYS require further processing of the normal output by the Sphinx module "StandaloneHTMLBuilder" Calling the script libdoc transform lmd <struct> results in the following effective call by the CODESYS LibDoc Scripting Collection for generating the LMD output:

cd <config-dir>
sphinx-build -b html -c <config-dir> -d Build\Frame\doctrees -t libdoc_lmd Frame Build\Frame\lmd

In order to assign the elements in the project tree of a CODESYS library project to the individual pages of the documentation, the file manifest.json is generated from the files objects-inv und frame.json. All files in the output folder (for example, Buid, Frame, and lmd) are then bundled in a zip archive with the file extension *.lmd.

objects-inv

Each HTML build by Sphinx creates a file named objects.inv that contains a mapping from the object names to the URIs relative to the HTML set root.

The original reason for this file is the "intersphinx" extension of Sphinx.

# Sphinx inventory version 2
# Project: SysFile
# Version: 3.5.5.0
# The remainder of this file is compressed using zlib.
[...]

frame.json

The libdoc generate <content> <frame> script creates the file frame.json, which contains information about the current library project.

{
   "header": {
       "created": "2015-02-02T13:28:28",
       "layout": "standard",
       "name": "frame.json",
       "version": "0.0.0.2"
   },
   "library": {
       "company": "System",
       "file": "SysFile.library",
       "title": "SysFile",
       "version": "3.5.5.0"
   }
}

manifest.json

The script libdoc transform lmd <struct> collects all information that is needed for processing the library documentation in the CODESYS library manager.

{
   "header": {
       "created": "2015-02-02T15:46:51",
       "name": "manifest.json",
       "version": "0.0.0.1"
   },
   "inventory": {
       "std:label": {
           ".sys_filetime": {
               "location": "SYS_FILETIME.html#sys-filetime",
               "name": "..."
           }
       }
   },
   "library": {
       "company": "System",
       "title": "SysFile",
       "version": "3.5.5.0"
   }
}

In the Sphinx project, the file conf.py provides numerous setting options. Detailed information about these settings are found in the Sphinx documentation for HTML options.

CHM Output Format

Calling the script libdoc transform chm <struct> provides a complete conversion of the Sphinx project into a file format that can be integrated into the CODESYS Online Help by means of the package designer. This format, designed by Microsoft, is generated by the program "HTML Workshop". It is used for transporting information that is required for displaying library documentation in the CODESYS Online Help. The data generated by Sphinx still has to be processed in order that the online help is displayed correctly. The file <lib-name>.hhc is reconstructed in such a way that the directory structure corresponds to the CODESYS standard and the correct symbols (books instead of folders) are displayed in the online help. In the Sphinx project, the file conf.py provides numerous setting options. Detailed information about these settings are found in the Sphinx documentation for HTML options.

Example of how to effectively call the CODESYS LibDoc Scripting Collection for generating a CHM file:

cd <config-dir>
sphinx-build -b htmlhelp -c . -d Build\Frame\doctrees -t libdoc_chm Frame Build\Frame\chm

This will produce the following list of files:

<library-name>.hhc <- Content/Structure
<library-name>.hhk <- Index/Keywords
<library-name>.hhp <- Project settings
<library-name>.stp <- Stop word list

The final call by the help compiler:

C:\Program Files (x86)\HTML Help Workshop\hhc.exe" "<path>\<library-name>.hhp``

If the "HTML Help Workshop" is not installed in the default directory, then the CODESYS LibDoc Scripting Collection cannot find the file hhc.exe. The environment variable LIBDOC_HHC must be set for adapting the scripting collection to these conditions.

Information about installing the "HTML Help Workshop" is found in the HTML Help Workshop.

PDF Output Format

Today, the PDF format (Portable Document Format) developed by Adobe Systems is an open ISO standard (International Organization for Standardization) for exchanging electronic documents. Converted documents in PDF look the same as when they are printed on paper, but they can also include hyperlinks. In the Sphinx project, the file conf.py provides numerous setting options. Detailed information about these settings are found in the Sphinx documentation for LaTeX options.

Calling the script libdoc transform latex <struct> generates a complete collection of LaTeX files from the Sphinx project.

Example of how to effectively call the CODESYS LibDoc Scripting Collection for generating a PDF file:

cd <config-dir>
sphinx-build -b latex -c . -d Build\Frame\doctrees -t libdoc_pdf Frame Build\Frame\latex

cd Build\Frame\latex
pdflatex <library-name>.tex
pdflatex <library-name>.tex
pdflatex <library-name>.tex
makeindex -s python.ist <library-name>.idx
pdflatex <library-name>.tex
pdflatex <library-name>.tex

After this process, the required PDF file is found in Build\Frame\latex\<library-name>.pdf. Information about installing the pdflatex program is found in TeX Live for Windows.

POT Output Format

In order for documentation to be available in different languages, the individual segments of text are collected in POT files (Portable Object Template) where the text segments of the original documentation are aligned with the segments for another language. These files are usually sent to a translation agency where the texts are translated and PO files generated for each language. The PO files are then used for generating a Sphinx project in each language.

Calling the script libdoc transform pot <struct> provides a complete language catalog for the Sphinx project. In addition, a language-specific catalog is created in the directory <struct>/_locale for each language.

Example of how to effectively call the CODESYS LibDoc Scripting Collection for generating a POT file:

cd <config-dir>
sphinx-build -b gettext -c . -d Build\Frame\pottrees Frame Build\Frame\pot