honeydipper

DipperCL Document Automatic Generation

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

  1. drivers.daemon.drivers.* - meta information for a driver
  2. systems.* - each system can have its meta information here
  3. systems.*.functions.* - each system function can have its meta information here
  4. systems.*.triggers.* - each system triggers can have its meta information here
  5. workflows.* - each workflow can have its meta information here
  6. agents.* - each agent can have its meta information here

The 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.

Documenting a Driver

Following fields are allowed under the meta field for a driver,

For each of the rawActions,

For each of the rawEvents,

For each of the RPCs,

For 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:
                ...
        ...

Document a System

Following fields are allowed under the meta field for a system,

For each of the functions,

For each of the triggers,

For 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 ...

Document a Workflow

Following fields are allowed under the meta field for a workflow,

For 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 ...

Document an Agent

Following fields are allowed under the meta field for an agent,

For 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 ...

Formatting

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

Building

In order to build the document for local viewing, follow below steps.

  1. install sphinx following the sphinx installation document
  2. install markdown extension for sphinx following the recommonmark installation document
  3. install the read the docs theme for sphinx following the readthedoc theme installation document
  4. clone the honeydipper-sphinx repo
    git clone https://github.com/honeydipper/honeydipper-sphinx.git
    
  5. generating the source document for sphinx
    cd honeydipper-sphinx
    docker run -it -v $PWD/docgen:/docgen -v $PWD/source:/source -e DOCSRC=/docgen -e DOCDST=/source honeydipper/honeydipper:latest docgen
    
  6. build the documents
    # cd honeydipper-sphinx
    make html
    
  7. view your documents
    # cd honeydipper-sphinx
    open build/html/index.html
    

Publishing

In order to including your document in the Honeydipper community repo section of the documents, follow below steps.

  1. clone the honeydipper-sphinx repo
    git clone https://github.com/honeydipper/honeydipper-sphinx.git
    
  2. modify the docgen/docgen.yaml to add your repo under the repos section
  3. submit a PR

Writing Liquid-safe docs

The 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.

The convention already in use

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.

What needs escaping

What does not work: a backslash

A 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.

The check that guards this

.github/workflows/docs-lint.yml runs whenever a pull request or a push touches docs/, and does two things:

  1. a real Jekyll build of docs/ using the same builder image and gem versions as GitHub Pages, so the check cannot go green while Pages goes red; and
  2. a delimiter gate that fails on {% or {{ left outside a raw fence, which is the only way to catch the silent class before merge.

Known limits: