This document describes how to generate the Gopherciser documentation.
The tools for generating the documentation first combine the documentation data and then generate a documentation.go
file and subsequently a settingup.md
file:
documentation.go
: Contains a set of variables that can be used for accessing the documentation programmatically.settingup.md
: A markdown formatted file to be rendered by a markdown reader or the GitHub project page.
The reason for having an intermediate "programmatically readable" step is to allow other projects to include parts of the documentation at compile time. Allowing the documentation to be read as code is easier than having other projects importing the documentation files.
To generate new documentation.go
and settingup.md
files after updating the documentation data, use the following command in the project root:
go generate
The Gopherciser main.go
file contains the following commands for go generate
:
//go:generate go run ./generatedocs/cmd/compiledocs
//go:generate go run ./generatedocs/cmd/generatemarkdown --output ./docs/settingup.md
To only generate a new documentation.go
file, use the following command:
go run ./generatedocs/cmd/compiledocs
--output string
: Filepath to the generated file. Defaults togeneratedocs/generated/documentation.go
.--data
: Comma separated filepaths to the data to read. Filepaths Defaults togeneratedocs/data
.
To only generate a new settingup.md
file, use the following command:
go run ./generatedocs/generate/generate.go --output ./docs/settingup.md
--output
: Defaults togeneratedocs/generated/settingup.md
.
The structure of the data
folder is as follows:
data
-> actions
-> action folders
-> config
-> config sections folders
-> extra
-> extra folders
-> groups
-> groups folders
-> groups.json
-> documentation.template
-> params.json
-> settingup.md.template
Data can be overloaded by passing a comma separated list to the --data
flag, e.g. --data=path/to/data1,path/to/data2
. The overload precedence goes from low to high within the list, meaning data1
will be overloaded by data2
.
The documentation structure for actions, groups and config sections follows the same pattern. They are all documented in three separate parts:
- Description
- Parameters
- Examples
The reason for the structure is to make the description and each parameter individually accessible when accessing the documentation programmatically. The description and examples parts are written directly as markdown files, located in the appropriate action, config or groups subfolder. The following example shows the folder structure for the changesheet
action:
data
-> actions
-> changesheet
-> description.md
-> examples.md
The parameters part is documented in the params.json
file. The following example shows the parameters for the changesheet
action:
{
"changesheet.id" : ["GUID of the sheet to change to."]
}
In the code for each parameter there is a doc-key
tag that connects the parameter to its documentation in the params.json
file. The following example shows the tags for ChangeSheetSettings
:
// ChangeSheetSettings settings for change sheet action
ChangeSheetSettings struct {
ID string `json:"id" displayname:"Sheet ID" doc-key:"changesheet.id" appstructure:"active:sheet"`
}
As enums cannot be reflected, they are documented as lists. The entries in the params.json
file are set to an array of strings, where the first string is the description of the parameter and the subsequent strings are sub items to the parameter. The following example shows the doc-key
for the type
parameter in the select
action:
Type SelectionType `json:"type" displayname:"Selection type" doc-key:"select.type"`
The doc-key
connects to the following entry in the params.json
file:
{
"select.type": [
"Selection type",
"`randomfromall`: Randomly select within all values of the symbol table.",
"`randomfromenabled`: Randomly select within the white and light grey values on the first data page.",
"`randomfromexcluded`: Randomly select within the dark grey values on the first data page.",
"`randomdeselect`: Randomly deselect values on the first data page.",
"`values`: Select specific element values, defined by `values` array."
]
}
The entry above renders the following markdown result:
* `type`: Selection type
* `randomfromall`: Randomly select within all values of the symbol table.
* `randomfromenabled`: Randomly select within the white and light grey values on the first data page.
* `randomfromexcluded`: Randomly select within the dark grey values on the first data page.
* `randomdeselect`: Randomly deselect values on the first data page.
* `values`: Select specific element values, defined by `values` array.
Groups are defined in the groups.json
file, which has the following structure:
- name: Name of the group
- title: Full title of the group
- actions: List of actions in the group
Example:
{
"name": "qseowActions",
"title": "Qlik Sense Enterprise on Windows (QSEoW) actions",
"actions": [
"deleteodag",
"generateodag",
"openhub"
]
}
If an action does not belong to a group, it is added to an Ungrouped actions
section.
Any subfolder in the extra
subfolder is added as a DocEntry in the Extra
map in documentation.go
.
The doccompiler packge has support for extending the generated and programmatically readable documentation in documentation.go
. The simplest way to extend the documentation.go
in this repository is to use the extenddocs package (which makes use of the extend functionality in the doccompiler
).
In a project which extends the github.com/qlik-oss/gopherciser
the following main
would implement a documentation extender with the same flags (--data
and --output
) as compiledocs
:
package main
import (
"github.com/qlik-oss/gopherciser/generatedocs/pkg/extenddocs"
// Make sure to register any new actions that shall be included in the
// extended documentation. In this case they are registered in the `init()`
// function of the `registeractions` package below.
_ "github.com/my-user/extended-gopherciser/registeractions"
)
func main() {
extenddocs.ExtendOSSDocs()
}
The extended settingup.md
shall then import the extended programatically readble documentation and use the genmd package to generate the markdown documentation.
package main
import (
"github.com/qlik-oss/gopherciser/generatedocs/pkg/genmd"
"github.com/my-user/extended-gopherciser/generatedocs/generated"
// Once again, make sure to register any new actions that shall be included in the
// extended documentation.
_ "github.com/my-user/extended-gopherciser/registeractions"
)
func main() {
genmd.GenerateMarkdown(&genmd.CompiledDocs{
Actions: generated.Actions,
Params: generated.Params,
Config: generated.Config,
Groups: generated.Groups,
Extra: generated.Extra,
})
}