gchq
Add reference section
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 >}} .
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
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.