Library Documentation

Note

CODESYS LibDoc Scripting Collection

This section is intended to clarify the current situation regarding documentation in the CODESYS source code.

The introduction of the CODESYS Store presented a platform for commercial distribution of CODESYS libraries. Because of this, this document is intended to summarize the most important demands on library developers. One central demand is as follows:

Each library should be delivered with documentation.
This documentation must be designed to ensure that the context-sensitive help (F1) functions correctly, that the presentation of the interfaces, parameters, etc. is attractive, and that their descriptions are available in the Library Manager.

CODESYS users are able to insert HTML tags into the comments of modules for controlling how the appearance is formatted in the library manager. However, this method is not recommended because it corrupts the legibility of the source code.

It is also possible for CODESYS users to create files using Microsoft “HTML Workshop”. These files can be added as an extension to the on-line help in a CODESYS setup. If all of the required steps are completed, then a user is able to select a data type in the source code of a POU and press F1 to see the respective page displayed in the online help.

All of these options are available now and greatly improve the usability of a library. Unfortunately, however, the required effort is often so extensive that only a few library developers do this. For this reason, we have started the development of a CODESYS LibDoc Scripting Collection to help significantly reduce the effort in developing attractive online help for libraries.

The CODESYS LibDoc Scripting Collection uses Sphinx, a Python-based script family that converts plain text files into hyperlinked documents with an attractive format. Sphinx knows what to link and how to format using simple formatting commands in the text files. This set of formatting commands forms what we refer to as reStructuredText. This markup language derives its strength not only from the power and directness of the rules implemented with reStructuredText, but also from the parsing and translating suite of another scripting collection called Docutils.

The CODESYS LibDoc Scripting Collection can automatically document a project by reading the JSON-exported CODESYS library source code. It can also process the comments of the IEC objects available in this source code, as well as hyperlink POUs, DUTs, GVLs, etc. With additional setup options, other document formats can be generated (for example, CHM or PDF) from your project source code, including attractive syntax highlighting, index listings, and glossary appendices.

We prefer the CODESYS LibDoc Scripting Collection because it allows authors to insert automatically generated documentation whenever it is needed, while at the same time maintaining high-quality, handwritten, tutorial-style content which we believe is the most effective kind of CODESYS library documentation.

Note

The following items must be considered when using the CODESYS LibDoc Scripting Collection:

  • HTML tags should no longer be included in the comments of a CODESYS project. Instead, another markup language should be used, such as “reStructured Text” or “reST”. This syntax will not compromise the legibility of the source code. In addition to formatting, it can also convey special CODESYS semantics as a result of its extensibility (for example, with the function GetTime and return type TIME).

  • The comments propagated throughout the respective CODESYS project are gathered automatically and converted to HTML in order for the Library Manager to display them in an appealing manner.

  • The comments propagated throughout respective CODESYS project are exported with the project structure into a framework document. Then a technical writer can add additional information (for example, tutorials and examples) and create a CHM file. This file can be delivered and installed with the library. Of course, such a file can also be translated into other languages to provide users of the library with online help pages in the respective languages.

Even if only some of these items have already been implemented in the currently available CODESYS versions, it is now important to consider this concept when developing a library. If all new libraries are provided with comments formatted in “reST”, then this will further improve both the usability of these libraries with each new CODESYS version and the appearance of the documentation in the library manager. The rules to follow now for formatting comments in CODESYS projects are reliable-fixed and have been ranked as very stable for many years. As the definition of these rules is not specific to CODESYS, there is no danger that the work of one day will be obsolete the next day. Adding well-formatted comments to the library according to these rules is not jeopardized by later changes to the syntax in the completed product.

Unfortunately, the comments from some of the libraries are not displayed well in the library manager in current CODESYS versions. However, for years we have followed a proven method:

“It is better to have good content presented in a less-than-perfect way today than to have no content presented beautifully tomorrow.”

The reflections stated above are based on the assumption that the documentation of a library is created while it is being developed. Another point of view has been found in cooperation with some customers. The CODESYS LibDoc Scripting Collection also can be used for creating the specification of a library. For this purpose, only the bodies of functions, modules, and data types are created and provided with comments in CODESYS. The CODESYS LibDoc Scripting Collection then generates a framework document (preferably a PDF) from this, which can be submitted to the customer of the library for further discussion. In this case, reworking of the framework document by a technical writer is neither necessary nor intended. The CODESYS LibDoc Scripting Collection will simply create an attractive appearance of the CODESYS project.

Examples of “reStructuredText”

Within the scope of CODESYS libraries, two examples are provided here:

  • Referencing symbols to each other in comments in the SysFile library

  • Using images in the SML_Basic library sources

Write the Docs is where the art and science of documentation can be practiced and appreciated. There are many people who write documentation, but there is no good place to find information, ask questions, or generally be a member of a community of those who write documentation.

On the Internet, there are many examples of how to use reStructuredText, Docutils, and the Sphinx toolchain. Some useful examples are as follows:

  • The Sphinx toolchain manual can be read as Source, PDF, or HTML.

  • The Jinja2 template engine publishes the respective manual as Source, PDF, or HTML.

  • The Django project also maintains its Documentation also in reStructuredText and publishes its Online Help – a nice example of how elegantly different versions of documentation can be accessed.

  • There are also documents that deal comprehensively with mathematical or physical topics. The Theoretical Physics Reference project uses reStructuredText for writing texts and formulas. The Sources of the book and presentation are available as PDF and HTML.

  • Read the Docs hosts documentation for the open-source community. It supports Sphinx documentation written with reStructuredText and pulls the code from a Subversion, Bazaar, Git, or Mercurial repository. Then it employs the Sphinx toolchain for building documentation and hosting it for customers. The transformed Source of the documentation for this project can be found as PDF and HTML.

  • There are currently two different options for generating a *.pdf file from reStructuredText:

    The book “Music for Geeks and Nerds” by Pedro Kroger was generated by Sphinx via the LaTeX Builder and then converted to PDF via the TeX toolchain.

    In contrast, the Online Version of the German translation the book “Python Reference” by David Beazley was generated by Sphinx with a rts2pdf extension. This extension is based on the open-source PDF Toolkit from ReportLab.

    The extra effort of installing TeX results in an widely-accepted, high-quality typeset (for example, clean margin alignment of paragraphs, including hyphenation). On the other hand, “rst2pdf” can be used in the short term for obtaining correct PDF files, however with lower quality typeset and no hyperlinks.