Honeydipper configuration language (DipperCL) supports storing meta information of the configurations such as the purpose of the
configuration, the fields or parameters definition and examples. The meta information can be used for automatic document generating and
publishing.
The meta information are usually recorded using meta field, or description field. They can be put under any of the below list of locations
drivers.daemon.drivers.* - meta information for a driversystems.* - each system can have its meta information heresystems.*.functions.* - each system function can have its meta information heresystems.*.triggers.* - each system triggers can have its meta information hereworkflows.* - each workflow can have its meta information hereagents.* - each agent can have its meta information hereThe description field is usually a simple string that will be a paragraph in the document immediately following the name of the entry.
The meta field is a map of different items based on what entry the meta is for.
Since the description field does not support formatting, and the it could be used for log generating at runtime, it is recommended to
not use the description field, and instead use a description field under the meta field.
Following fields are allowed under the meta field for a driver,
description - A list of items to be rendered as paragraphs following the top level descriptionconfigurations - A list of name, description pairs describing the items needed to be configured for this drivernotes - A list of items to be rendered as paragraphs following the configurationsrawActions - A list of meta information for rawAction, see below for detailrawEvents - A list of meta information for rawEvents, see below for detailRPCs - A list of meta information for RPCs, see below for detailFor each of the rawActions,
description - A list of items to be rendered as paragraphs following the name of the actionparameters - A list of name, description pairs describing the context variables needed for this actionreturns - A list of name, description pairs describing the context variables exported by this actionnotes - A list of items to be rendered as paragraphs following the above itemsFor each of the rawEvents,
description - A list of items to be rendered as paragraphs following the name of the eventreturns - A list of name, description pairs describing the context variables exported by this eventnotes - A list of items to be rendered as paragraphs following the above itemsFor each of the RPCs,
description - A list of items to be rendered as paragraphs following the name of the RPCparameters - A list of name, description pairs describing the parameters needed for this RPCreturns - A list of name, description pares describing the values returned from this RPCnotes - A list of items to be rendered as paragraphs following the above itemsFor example, to define the meta information for a driver:
---
drivers:
daemon:
drivers:
my-driver:
description: The driver is to enable Honeydipper to integrate with my service with my APIs.
meta:
description:
- ... brief description for the system ...
configurations:
- name: foo
description: A brief description for foo
- name: bar
description: A brief description for bar
...
rawEvents:
myEvent:
description:
- |
paragraph .....
returns:
- name: key1
description: description for key1
- name: key2
description: description for key2
notes:
- some notes as text
- example:
...
...
Following fields are allowed under the meta field for a system,
description - A list of items to be rendered as paragraphs following the top level descriptionconfigurations - A list of name, description pairs describing the items needed to be configured for this in system datanotes - A list of items to be rendered as paragraphs following the configurationsFor each of the functions,
description - A list of items to be rendered as paragraphs following the name of the functioninputs - A list of name, description pairs describing the context variables needed for this functionexports - A list of name, description pares describing the context variables exported by this functionnotes - A list of items to be rendered as paragraphs following the above itemsFor each of the triggers,
description - A list of items to be rendered as paragraphs following the name of the triggerexports - A list of name, description pares describing the context variables exported by this triggernotes - A list of items to be rendered as paragraphs following the above itemsFor example, to define the mata information for a system,
---
systems:
mysystem:
meta:
description:
- ... brief description for the system ...
configurations:
- name: key1
description: ... brief description for key1 ...
- name: key2
description: ... brief description for key2 ...
notes:
- ... some notes ...
- example: |
... sample in yaml ...
data:
...
functions:
myfunc:
meta:
description:
- ... brief description for the function ...
inputs:
- name: key1
description: ... brief description for key1 ...
- name: key2
description: ... brief description for key2 ...
exports:
- name: key3
description: ... brief description for key3 ...
- name: key4
description: ... brief description for key4 ...
notes:
- ... some notes ...
- example: |
... sample in yaml ...
Following fields are allowed under the meta field for a workflow,
description - A list of items to be rendered as paragraphs following the top level descriptioninputs - A list of name, description pairs describing the context variables needed for this workflowexports - A list of name, description pares describing the context variables exported by this workflownotes - A list of items to be rendered as paragraphs following the above itemsFor example, to define the mata information for a workflow,
---
workflows:
myworkflow:
meta:
description:
- ... brief description for the workflow ...
inputs:
- name: key1
description: ... brief description for key1 ...
- name: key2
description: ... brief description for key2 ...
exports:
- name: key3
description: ... brief description for key3 ...
- name: key4
description: ... brief description for key4 ...
notes:
- ... some notes ...
- example: |
... sample in yaml ...
Following fields are allowed under the meta field for an agent,
description - A list of items to be rendered as paragraphs following the top level descriptioninputs - A list of name, description pairs describing the context variables needed for this agentexports - A list of name, description pairs describing the context variables exported by this agentnotes - A list of items to be rendered as paragraphs following the above itemstools - A list of name, description pairs describing the tools available to this agentFor example, to define the meta information for an agent,
---
agents:
myagent:
meta:
description:
- ... brief description for the agent ...
inputs:
- name: key1
description: ... brief description for key1 ...
exports:
- name: key2
description: ... brief description for key2 ...
tools:
- name: tool1
description: ... brief description for tool1 ...
notes:
- ... some notes ...
- example: |
... sample in yaml ...
Both description and notes fields under meta support formatting. They accept a list of items that each
will be rendered as a paragraph in the documents. The only difference between them is the location where they will appear
in the documents.
Honeydipper docgen uses sphinx to render the documents, so the source document is in rst format. You can use
rst format in each of the paragraphs. You can also let docgen to format your paragraph by specify a data structure
as the item instead of plain text.
For example, plain text paragraph,
description:
- This is a plain text paragraph.
Highlighting the paragraph, see sphinx document for detail on highlight type.
notes:
- highlight: This paragraph will be highlighted.
- highlight: This paragraph will be highlighted with type `error`.
type: error
Specify a code block,
notes:
- See below for an example
- example: | # by default, yaml
---
rules:
- when: ...
do: ...
- example: |
func dosomething() {
}
type: go
In order to build the document for local viewing, follow below steps.
read the docs theme for sphinx following the readthedoc theme installation documenthoneydipper-sphinx repo
git clone https://github.com/honeydipper/honeydipper-sphinx.git
cd honeydipper-sphinx
docker run -it -v $PWD/docgen:/docgen -v $PWD/source:/source -e DOCSRC=/docgen -e DOCDST=/source honeydipper/honeydipper:latest docgen
# cd honeydipper-sphinx
make html
# cd honeydipper-sphinx
open build/html/index.html
In order to including your document in the Honeydipper community repo section of the documents, follow below steps.
honeydipper-sphinx repo
git clone https://github.com/honeydipper/honeydipper-sphinx.git
docgen/docgen.yaml to add your repo under the repos sectionThe docs/ directory is published by GitHub Pages, which runs every file
through Liquid before Markdown conversion. So {% and {{ are
not free text here — not even inside a fenced code block.
There are two failure classes, and only one of them makes any noise:
| Delimiter | Failure mode | What you see |
|---|---|---|
{% … %} |
hard error | The Pages build fails and the site is not updated at all. |
{{ … }} |
silent | The build passes, the expression renders empty, and your text simply disappears. |
The whitespace-control variants — {%-, -%}, {{-,
-}} — are the same delimiters and behave identically.
Because the second class keeps the build green, a passing build is not proof that the page renders correctly. GitHub Pages will happily publish a page with holes in it.
Wrap the literal example in the raw / endraw HTML-comment pair. Put the
opening comment on the line above the fenced block and the closing comment on
the line below it; both are HTML comments, so they are invisible in the
rendered page but perfectly visible in the source on GitHub:
{%- if .options.enable_feature_x %}
systems:
feature_x:
data:
foo: bar
{%- end %}
For an inline mention, wrap just the code span:
Use <!-- -->`{{ .ctx.value }}`<!-- --> to interpolate a value.
This is established practice, not a new invention — it is already used throughout interpolation.md, workflow.md, configuration.md and developer.md.
{% … %}, including {%- … -%}{{ … }}, including {{- … -}}${{ github.sha }} — Liquid only sees the inner
{{ ... }}, so these need the same treatmentA backslash does not escape anything for Liquid. This line still parses as a Liquid output tag, emits a warning, and renders only the backslash:
escaped_value: \{{ .ctx.value }}
That is worth knowing because Honeydipper itself uses a leading backslash as an
escape mechanism — the two are unrelated. Wrap the example in the raw /
endraw pair if you need to show a backslash escape; the rendered page then
shows the literal text, which is exactly what documentation needs.
.github/workflows/docs-lint.yml runs whenever a pull request or a push
touches docs/, and does two things:
docs/ using the same builder image and gem
versions as GitHub Pages, so the check cannot go green while Pages goes
red; and{% or {{ left outside a raw
fence, which is the only way to catch the silent class before merge.Known limits: