This is a guide to the NetKernel documentation system.
Documentation is written as plain/text and may be in any of a number of Wiki dialects. If no syntax declaration is made on the first line then MediaWiki syntax is the default. The following section has guides to each syntax.
The NetKernel wiki engine supports extensible macro engines.
A number of "built-in" macro engines may be used with your documents to style xml, java source etc. For details see this reference guide.
You may also add your own Macro Engines.
If you wish to include a human readable rendering of an endpoint's metadata you may use the "endpoint" macro containing the id of your endpoint
Documentation is published in two phases. First a text file is made visible to the documentation system by creating an entry in res:/etc/system/Docs.xml in your module. Secondly individual documents can be structured into books by referencing them in res:/etc/system/Books.xml
When you create a module with the new module wizard it will automatically construct the required Docs.xml and Books.xml in the module's etc/system/ directory and provide some stubbed out documents as a starting point.
The documentation system creates a master index of documentation by searching all of the public spaces for resources called res:/etc/system/Docs.xml - this must be a documentation list with the following structure...
The id entry must be system-wide unique so that documents can be linked and structured into books.
The category field indicates that the document should appear in the Component Reference Guide. Category is a space delimited list of categories. To indicate that this is a document you must include the value doc.
Other category labels include:
For example to list a document in the transport section you would have
The documentation system presents structured books by searching all of the public spaces for resources called res:/etc/system/Books.xml - this must be a book list with the following structure...
Each item has an id attribute which is the reference to the document id. Items may contain further items in a tree thereby providing the structure of the book. If an item has an @title attribute it will be used as an alternative (usually shorter) title for the menu listing.
Books.xml can contain any number of book definitions but each book id must be globally unique.
You may provide a book icon by specifying the
Modern browsers also support SVG so your icon can be a scalable vector SVG...
If you don't have the artistic inclination to create your own icon you can also use Fontawesome icons like this...
The documentation engine will detect and cross link document ids and system endpoint ids.
For example this document has id doc:sysadmin:guide:doc:editing it can be linked from any other document using wiki specific syntax...
System identifiers may also be used as link ids. For example the Groovy language runtime has id GroovyRuntime and is linked to with
[[GroovyRuntime|The Groovy Runtime]]
"The Groovy Runtime":GroovyRuntime
System links will take you from the documentation application to the Space Browser. Here is a live link to the Groovy runtime endpoint in the space browser.
The documentation system uses inline W3C standard SVG vector graphics for diagrams and line art. To see these images you must have a modern web browser that supports XHTML and native SVG rendering.
Image: Three interlocking Red, Green, Blue circles
Please note, Microsoft Internet Explorer does not implement W3C standard XHTML nor SVG vector images and so is incapable of correctly viewing this W3C standards complient documentation correctly - please upgrade to one of the browsers suggested above
Make an entry for the image resource in your module's etc/system/Docs.xml file. Like this...
This "document entry" will be aggregated into the set of all document id's and so be a known resource in the NK document system.
The documentation system provides a useful public REST service /doc/source/[document identifier] which serves the raw binary stream of any specified document identifier in the doc system.
Its operational pattern is to lookup the full resource identifier for a given document id, it also discovers the resource's home address space. It then performs a wormhole request for the resource and serves it as a BinaryStream.
It follows that you can get direct wormhole access to images from deep inside your module.
So in a document, here's how we might embed "some-image.png" (as registered in the example
It follows that you can use this service directly as the URL in an HTML image link too. Here's the same thing done with raw HTML...
The documentation system is built on the Wiki resource model library.
The terminology used to describe documents follows standard W3C / IETF best practice. The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when EMPHASIZED, are to be interpreted as described in IETF RFC 2119.