Add reference section
- 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
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