Add reference section

[at055612]

Add a section called Reference as a sibling to User Guide. This can then contain the following children

• Pipeline Elements - Basically relocate this page https://gchq.github.io/stroom-docs/docs/user-guide/pipelines/element-reference/
• Document Types - One child page per doc type (.e.g feed, dictionary, index, etc.) with description of what they, what the settings are, what they are used by, anything else useful.
• XSLT functions - A migration of https://gchq.github.io/stroom-docs/docs/user-guide/pipelines/xslt/xslt-functions/
• Dashboard Expression Functions - Maybe one child page for function group (a migration of https://gchq.github.io/stroom-docs/docs/user-guide/dashboards/expressions/)
• Glossary - Relocate https://gchq.github.io/stroom-docs/docs/glossary/
• StroomQL Keywords - One page for all keywords with a anchor heading for each.

To make things easier to maintain, all the XSLT funcs need a java annotation that provides all the documentation for the function, including all the args (with types). This would follow a similar pattern to the stroom.dashboard.expression.v1.FunctionDef annotation and means the content can be largely/fully auto generated from code.

We could then have a short codes like pipe-elm (already got this), document, xslt-func and expr-func that would give you a link to the right place in the reference and some visual thing like the icon for the document or the pipe element lozenge. This means the content write doesn't have to worry about where the reference page is, just add something simple like {{< xslt-func "lookup >}} .

[at055612]

For the content generated from annotations, it would be nice if it was written to say one file per annotated thing. We then need a way of including those files in the main human editable content, e.g. so you can have all the generated name/description/args stuff next to some human produced content, e.g. more detailed description, examples, etc. This means we don't have to mix auto-generated and human-generated content in the same files, which would be a lot cleaner, clearer for the editor and easier to manage with git and the generator.

The potential way to do this is to get the generator to convert the annotations to one json file per annotated thing. We then write a custom short code for each type of thing (e.g. one for xslt funcs, one for pipe elements, etc.), which reads the json and renders it to html. The human edited content can then include a short code call for each item. This keeps the generated content away from the editor and means the java code doesn't have to generate markdown. We could still allow the description in the annotation to be markdown for richer descriptions. The shortcode would just need to convert this description markdown into html.

Examples of how to read from json here https://gohugo.io/templates/data-templates/ and https://www.youtube.com/watch?v=zJjJuS7LgS8

[at055612]

We could potentially walk the config object tree and produce a json object containing a flat list of props, each with full path, type and description. We can then have a short code that will render this into a nice table of properties.

As we have more classes in stroom to generate json for the docs, it might be worth having a single entry point class in stroom that can be called by a shell script in stroom-docs to update everything in one go.

[at055612]

As we have more classes in stroom to generate json for the docs, it might be worth having a single entry point class in stroom that can be called by a shell script in stroom-docs to update everything in one go.

The class that currently generates all the docs content is stroom.app.docs.GenerateAllDocumentation

[at055612]

For the xslt/expr funcs it would make sense for each func to have an optional .md file in the stroom repo. The annotation would describe the args for each overload and a short description. The .md file would then provide an additional more detailed description that could include example usage and the like.

The UI could harness the anno + .md file to render function help.

If all content for a func is contained in the anno+md there may be no need for the shortcode approach described in #78 (comment) as we can auto-gen all the content via java code.

The function anno could maybe do with a seeAlso to capture links to other named funcs.

Some work was already started before this comment was written
#113
gchq/stroom#5156