Support externally created documentation

Current Situation

• Users can create job documentation in XML files. The JOE job editor provides the functionality to generate the respective XML files from user input.
• Such documentation files have to be linked to a job, e.g. by storing files in the ./jobs directory and following the given naming convention.

Desired Behavior

• Users would like to create documentation with any sort of tool:
  • this includes - but is not limited to - use of JSDoc that would document sources of JavaScript jobs and monitors.
    • JSDoc generated documentation includes the JavaScript source code and therefore would make visible JavaScript files that are used in jobs and monitors via the <include> element. Currently users cannot visualize the contents of such files - not with JOE and not with the JOC Cockpit.
    • JSDoc generated documentation comes as a single HTML file that should be visible with the JOC Cockpit.
  • this suggests to support any sort of HTML based documentation created with an HTML editor or generator.
  • this suggests support for lightweight markup for HTML representation as e.g. created with markdown syntax.
  • this suggests ongoing support for structured documentation in an XML format such as used by the JOE job editor. However, the presentation should be done in HTML, e.g. by use of individual stylesheets.
• Users would like to add documentation to any JobScheduler objects such as jobs, job chains, process classes, locks etc.
• The documentation should be visible with the JOC Cockpit for individual objects.

Limitations

• The import of documentations doesn't allow all file formats. Allowed formats are primarily:
  • html
  • xml
  • markdown (must have the file extension 'md' or 'markdown')
  • pdf
• The following file formats are also allowed, since they can be relatively addressed as external files
  • xsl (xml with the file extension 'xsl' or 'xslt')
  • images (gif, jpeg, png)
  • javascript
  • css
• If an html file contains links with a relative address then the linked file has to be imported too or an http address should be used.
• Further file formats which are used as embedded objects in an html file such as an audio file can be displayed but needs an http address instead of a relative address.
• Markdown files are converted to html when they are to be displayed
  • They have to match the syntax of John Gruber
  • During the conversion, a default css file ("/sos/css/default-markdown.css") is used and the title of the page is the name of the markdown file.
  • The markdown can start with reference-style links which are invisible.
    • These links can be used as header information for title and css file
    • [css]: http://myHost/my.css or relative [css]: my.css
    • [title]: myTitle