opsi documentation generator

Introduction

The opsi-doc-generator is a program to create documentation in asciidoc format from the following sources:

opsi-script library files (opsi-script)
opsi webservice interface definition files (python) (implementation is in progress)

Why asciidoc as output ?

asciidoc is the standard format for all opsi documentation
asciidoc is a base format to create documents in different formats like html, pdf, epub, docbook, …

The documentation is created from the information, that is extracted from the source code. From the source code opsi-doc-generator knows the definition of opsi-script defined functions and can get the information from there.
There may be special markers in comments which hold additional information on the level of file, function and parameter.

opsi-doc-generator program

There are two variants of this program:

The GUI Version opsi-doc-generator-gui:
The CLI Version opsi-doc-generator:

$ ./opsi_doc_generator --help
Creates asciidoc from commented opsiscript library code
and calls asciidoctor to convert asciidoc to html
and shows created html file in browser.
opsi_doc_generator
Version: 4.1.0.0
Usage:
opsi_doc_generator [Options] inputfile
Options:
 --help -> write this help and exit

You will find this program for Linux and Windows as opsi packages in the contribute area on download.uib.de

opsi-doc-generator marker

There are three different levels where information can be found in a source file:

file
function (may be more than one in a file)
function parameter (may be more than one in a function)

Every marker starts with the language specific comment char (opsiscript=';') followed by the the '@' char and the marker identifier string.

Every allowed marker can occur never, once or multiple times on a level. If a marker occurs multiple times, all lines with this marker are concatenated.

After a marker one or more space chars have to be used before the information starts.

opsi-script markers allowed on the file level

;@author
;@email
;@date
;@copyright
;@version
;@filedesc Description of file

opsi-script markers allowed on the function level

;@author Author (if absent, author of file is used)
;@email email address (if absent, email of file is used)
;@date Date (if absent, date of file is used)
;@copyright copyright (if absent, copyright of file is used)
;@version version (if absent, version of file is used)
;@Description Description of function
;@Returns Return value of function
;@OnError What happens in the case of an error
;@SpecialCase What happens in known special unexpected cases like empty input, no network, and so on
;@Requires
;@References The name of an other function in this file that are related to this function. only one per line. For multiple references use multiple lines
;@Links
;@Example An example for the use of this function.
Examples are in most cases multiline with idents. The start of the information in the first example line defines the base ident. Idents have to be done with space chars only (no tabs).

opsi-script markers allowed on the function parameter level

;@ParamDesc_<praram name> Description of the parameter <praram name>
;@ParamAdvice_<praram name> Advice for the parameter <praram name>. That may be for example used for restrictions of valid values.

opsi-doc-generator examples

opsi-script markers on the file level

;@author          detlef oertel
;@email           d.oertel@uib.de
;@date            17.4.2018
;@copyright       AGPLv3
;@version         1.0
;@filedesc        Collection of functions that manipulate the opsi backend via opsi service call

opsi-script markers on the function and parameter level

;@author          detlef oertel
;@date            17.5.2018
;@Description     Sets for the given list of opsi productIds the action request
;@Description     to 'setup' (also resolving the dependencies)
;@Returns         Returns string "true" if all is ok
;@OnError         Returns string "false"
;@SpecialCase     Works only in opsi service mode (not in interactive or batch mode)
;@References
;@Links
;@ParamDesc_$productlist$     List of opsi product Ids
;@ParamAdvice_$productlist$
;@Example     [actions]
;@Example     DefStringlist $productlist$
;@Example
;@Example     set $productlist$ = CreateStringList("opsi-logviewer","opsi-configed")
;@Example     if not(stringtobool(setProductsToSetup($productlist$)))
;@Example       comment "call of setProductsToSetup failed"
;@Example     endif