gchq / gchq/stroom-docs

Add reference section

Open
#78 4 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Shell
Stars
31
Forks
30
Avg merge
5h 17m
Merged PRs (30d)
2

Description

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 >}}` .

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing pages linked in the issue and the current User Guide structure. Read the existing stroom.dashboard.expression.v1.FunctionDef annotation and assess how the proposed XSLT metadata and shortcodes would fit. Done means the Reference section, migrated child pages, generated function documentation, and cross-reference shortcodes are implemented consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
content, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.