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
drivers.daemon.drivers.*
- meta information for adriver
systems.*
- 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 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,
description
- A list of items to be rendered as paragraphs following the top level descriptionconfigurations
- A list ofname
,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 forrawAction
, see below for detailrawEvents
- A list of meta information forrawEvents
, see below for detailRPCs
- A list of meta information forRPCs
, see below for detail
For each of the rawActions
,
description
- A list of items to be rendered as paragraphs following the name of the actionparameters
- A list ofname
,description
pairs describing the context variables needed for this actionreturns
- A list ofname
,description
pairs describing the context variables exported by this actionnotes
- A list of items to be rendered as paragraphs following the above items
For each of the rawEvents
,
description
- A list of items to be rendered as paragraphs following the name of the eventreturns
- A list ofname
,description
pairs describing the context variables exported by this eventnotes
- A list of items to be rendered as paragraphs following the above items
For each of the RPCs
,
description
- A list of items to be rendered as paragraphs following the name of the RPCparameters
- A list ofname
,description
pairs describing the parameters needed for this RPCreturns
- A list ofname
,description
pares describing the values returned from this RPCnotes
- A list of items to be rendered as paragraphs following the above items
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
,
description
- A list of items to be rendered as paragraphs following the top level descriptionconfigurations
- A list ofname
,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 configurations
For each of the functions
,
description
- A list of items to be rendered as paragraphs following the name of the functioninputs
- A list ofname
,description
pairs describing the context variables needed for this functionexports
- A list ofname
,description
pares describing the context variables exported by this functionnotes
- A list of items to be rendered as paragraphs following the above items
For each of the triggers
,
description
- A list of items to be rendered as paragraphs following the name of the triggerexports
- A list ofname
,description
pares describing the context variables exported by this triggernotes
- A list of items to be rendered as paragraphs following the above items
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
,
description
- A list of items to be rendered as paragraphs following the top level descriptioninputs
- A list ofname
,description
pairs describing the context variables needed for this workflowexports
- A list ofname
,description
pares describing the context variables exported by this workflownotes
- A list of items to be rendered as paragraphs following the above items
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 ...
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.
install sphinx following the sphinx installation document
install markdown extension for sphinx following the recommonmark installation document
install the
read the docs
theme for sphinx following the readthedoc theme installation documentclone the
honeydipper-sphinx
repogit clone https://github.com/honeydipper/honeydipper-sphinx.git
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:1.0.0 docgen
build the documents
# cd honeydipper-sphinx make html
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.
clone the
honeydipper-sphinx
repogit clone https://github.com/honeydipper/honeydipper-sphinx.git
modify the
docgen/docgen.yaml
to add your repo under therepos
sectionsubmit a PR