The appearance of the documentation that is generated with the CODESYS LibDoc Scripting Collection can be customized extensively to individual requirements. Various adjustments are made when documentation is generated:
Templates (contents and structure)
Themes (appearance, color scheme, logo, page layout)
In the first step of documentation generation by libdoc generate, a file is generated in reStructuredText format for each element in a CODESYS library project. The contents, order, and appearance are in this file are defined by a template that is assigned to the element type. These templates are formatted for processing by the Jinja2 template engine.
The following is a sample template for documentation generation for a user-defined data structure:
{% extends "dut-object.rst" %}
{% block header %}
{{ super() }}
.. first line of struct-object.rst template
{% endblock %}
{% block title %}
{% set iname = particle.name %}
{% set name = iname|se %}
{% set prefix = particle.prefix %}
{% if prefix %}
{% set title = name + " (STRUCT; Prefix " + prefix + ")" %}
{% else %}
{% set title = name + " (STRUCT)" %}
{% endif %}
.. Index::
single: Struct; {{ iname }}
single: {{ iname }}
{{ particle.target }}
{{ title }}
{{ '-' * title|count }}
{% endblock %}
{% block declaration %}
{{ particle.declaration }}
{% endblock %}
{% block footer %}
.. last line of struct-object.rst template
{{ super() }}
{% endblock %}
A CODESYS library project "SysFile.library" includes a structure with the name "SYS_FILETIME":
After processing by the tample engine, the generated file "SYS_FILETIME.rst" may look like this:
.. first line of object.rst template
.. first line of dut-object.rst template
.. first line of struct-object.rst template
.. <% set key = ".SYS_FILETIME" %>
.. _`.SYS_FILETIME`:
.. <% merge "object.Defines" %>
.. <% endmerge %>
.. Index::
single: Struct; SYS_FILETIME
single: SYS_FILETIME
.. _`SYS_FILETIME`:
SYS_FILETIME (STRUCT; Prefix ft)
--------------------------------
TYPE SYS_FILETIME : STRUCT
.. <% merge "object.Doc" %>
| File TIME
| Timestamps of the specified file.
.. <%- endmerge %>
InOut:
+----------------------------+-------+-------------------------------+
| Name | Type | Comment |
+============================+=======+===============================+
| :index:`tCreation` | UDINT | Creation time of the file |
+----------------------------+-------+-------------------------------+
| :index:`tLastAccess` | UDINT | Time of as access to the file |
+----------------------------+-------+-------------------------------+
| :index:`tLastModification` | UDINT | Time of last modification |
+----------------------------+-------+-------------------------------+
.. last line of struct-object.rst template
.. last line of dut-object.rst template
.. last line of object.rst template
A template collection is supplied with the CODESYS LibDoc Scripting Collection. For learning about the structure of this collection, refer to the directory C:\Program Files (x86)\3S CODESYS\CODESYS\DocScripting\3.5.6.0\templates of the CODESYS installation. To customize this collection, we recommend that you copy these files to another folder and edit the copied files. The customized template collection is available for use at the next script call after they are referenced via the environment variable LIBDOC_TEMPLATES. Example:
LIBDOC_TEMPLATES = D:\TecDoc\General\Templates
A precise and detailed description of this process is beyond the scope of this document. However, this example shows comprehensive the structure and contents of the library documentation can be controlled by the appropriate template design. We highly recommend that you learn more from Template Designer Documentation von Jinja2.
Sphinx supports changing the appearance of HTML-based output with themes. A Sphinx theme is a collection of HTML templates, stylesheet, and other static files. In addition, it has a configuration file which specifies the inherited theme, the highlighting style to use, and the options for customizing the look and feel of a theme. Themes are meant to be universal so they can be used for any project without having to be modified.
CODESYS LibDoc Scripting Collection is equipped with a template displaying the documentation appropriately in HTML, LMD, and CHM formats.
For learning about the structure of this collection, refer to the directory C:\Program Files (x86)\3S CODESYS\CODESYS\DocScripting\3.5.5.0\themes of a CODESYS installation. There are two options for customizing this collection:
After the libdoc generate step, there is a "Theme" folder in addition to the file with the library project. In this folder, you can make changes to the appearance for the documentation of the current library.
If the appearance of the documentation should be changed in general for all future libraries, then it makes sense to copy the files from the "Theme" folder to a new folder and edit the files there. The customized template collection is available for use at the next script call after they are referenced via the environment variable LIBDOC_THEME. Example:
LIBDOC_THEME = D:\TecDoc\General\Themes
Although there is a general method for PDF output from the Sphinx source files, Sphinx does not generate PDFs by itself. Sphinx provides a LaTeX builder which generates a collection of LaTeX source files. When using LaTeX for creating PDFs, it is necessary to customize the LaTeX output by means of options in the Sphinx config file. This method is less convenient than customizing the HTML themes that Sphinx uses for HTML-based output. Please refer to the Sphinx documentation of the Sphinx LaTeX-Builder.
Another option for creating PDF files from a Sphinx project is to use the Sphinx extension from the rst2pdf project.
