-
Notifications
You must be signed in to change notification settings - Fork 106
/
config_schema.json
181 lines (181 loc) · 8.33 KB
/
config_schema.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
"$id": "https://github.com/coveooss/json-schema-for-humans/config_schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "JSON Schema for Humans configuration file",
"description": "Choose how to generate JSON Schema for Humans documentation file.\n\nConfiguration parameters can be provided in several ways:\n\n- On the CLI using `--config parameter_name=value` (example: `--config template_name=flat`)\n- On the CLI using a config file `--config-file config.json`\n- From code, by providing a GenerationConfiguration object to the called generation method.",
"properties": {
"description_is_markdown": {
"type": "boolean",
"default": true,
"description": "(HTML outputs only)\nWhether to consider the description as Markdown and render it accordingly."
},
"description_safe_mode": {
"enum": [null, "escape", "replace"],
"default": "escape",
"description": "(HTML outputs only)\n(Only used with `description_is_markdown`)\nHow are HTML tags in descriptions handled. Correspond to the `safe_mode` option of the markdown2 library.\n\n- \"escape\": Escape all HTML tags in descriptions\n- \"replace\": Replace HTML tags with `[HTML_REMOVED]`\n- null: Allow HTML in descriptions"
},
"expand_buttons": {
"type": "boolean",
"default": false,
"description": "Add an `Expand all` and a `Collapse all` button at the top of the generated documentation."
},
"show_breadcrumbs": {
"type": "boolean",
"default": true,
"description": "For each property, show the relative place of that property in the schema."
},
"collapse_long_descriptions": {
"type": "boolean",
"default": true,
"description": "If a description is considered big, show only the beginning and add a `Read more` button."
},
"collapse_long_examples" : {
"type": "boolean",
"default": true,
"description": "If an example is considered big, collapse it, it can be displayed with a `Show` option."
},
"link_to_reused_ref": {
"type": "boolean",
"default": true,
"description": "If several `$ref` points to the same definition, only render the documentation for this definition the first time. All other occurrences are replaced by an anchor link to the first occurrence. The first occurrence is the one that is the least nested from the top of the schema and appears first in that nesting level.\n\n*Note*: If this option is off and the schema contains recursive definitions, the generation will crash!"
},
"recursive_detection_depth": {
"type": "integer",
"default": 25,
"description": "*Advanced option*\nIf `link_to_reused_ref` is false and a `$ref` in the schema refers to a parent of itself, we would get a `RecursionError` trying to render the documentation. To avoid this, each reference is checked for circular references.\n\nThis option determines the number of times to recursively follow definitions looking for a circular reference.\n\nIn other words, if a schema has a deeply nested element that refers to itself, this option may need to be increased."
},
"deprecated_from_description": {
"type": "boolean",
"default": false,
"description": "Mark a property as deprecated (with a big red badge) if the description contains the string `[\u200BDeprecated`."
},
"default_from_description": {
"type": "boolean",
"default": false,
"description": "Extract the default value of a property from the description like this: ``[Default `the_default_value`]``.\n\nThe default value from the \"default\" attribute will be used in priority."
},
"copy_css": {
"type": "boolean",
"default": true,
"description": "Copy `schema_doc.css` to the same directory as `RESULT_FILE` after generation."
},
"copy_js": {
"type": "boolean",
"default": true,
"description": "Copy `schema_doc.min.js` to the same directory as `RESULT_FILE` after generation.\n\nThis file contains the logic for the anchor links."
},
"template_name": {
"type": "string",
"enum": [
"flat",
"js",
"js_offline",
"md",
"md_nested"
],
"default": "js",
"description": "The name of the built-in template to use to render the documentation.\n\n`js` is the default and uses javascript for anchor links, collapsible sections and tabs.\n\n`js_offline` is identical to `js` except that all CSS, fonts and JavaScript are bundled for offline use.\n\n`flat` uses no javascript, but has no interactivity.\n\n`md` is the markdown template.\n\n`md_nested` is the markdown template with collapsible nested sections."
},
"custom_template_path": {
"type": "string",
"default": null,
"description": "Path to a custom Jinja2 template file.\n\nThere can be multiple files to split the template, but this path should be the entry point.\n\nIf no output file is specified, the extension of the template file will be used to determine the output documentation extension. i.e. if the template is in ./custom_template/content.html, the resulting documentation will have the html extension."
},
"show_toc": {
"type": "boolean",
"default": true,
"description": "Whether to render table of contents."
},
"examples_as_yaml": {
"type": "boolean",
"default": false,
"description": "Whether to display examples as YAML instead of JSON"
},
"old_anchor_links": {
"type": "boolean",
"default": false,
"description": "Generate HTML ids for anchor links without special characters (keep only letters, digits, `_`, and `-`).\n\nThis is the old behaviour and is only needed for browsers that do not support HTML 5."
},
"markdown_options": {
"type": "object",
"default": {
"fenced-code-blocks": {
"cssclass": "highlight jumbotron"
},
"tables": null,
"breaks": {"on_newline": true, "on_backslash": true}
},
"description": "(Only used with `description_is_markdown`)\n[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions.",
"examples": [
{
"fenced-code-blocks": {
"cssclass": "highlight jumbotron"
},
"tables": null,
"break-on-newline": true,
"cuddled-lists": true
}
]
},
"template_md_options": {
"type": "object",
"description": "specific options to md template",
"properties": {
"badge_as_image": {
"type": "boolean",
"description": "if true generate badges(eg: optional, required) using embedded image (https://img.shields.io).\n\n if false, use text instead",
"default": false
},
"show_heading_numbers": {
"type": "boolean",
"description": "if true generate heading numbers to correspond to table of contents.\n\n if false, do not generate heading numbers",
"default": true
},
"show_array_restrictions": {
"type": "boolean",
"description": "if true generate array restrictions section.\n\n if false, do not generate",
"default": true
},
"properties_table_columns": {
"type": "array",
"description": "array of column names to display in the properties table.\n\n if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description']",
"items": {
"type": "string",
"enum": [
"Property",
"Pattern",
"Type",
"Deprecated",
"Definition",
"Title/Description"
]
}
}
}
},
"with_footer": {
"type": "boolean",
"description": "Whether to show the footer linking to the library repo and with the generation datetime",
"default": true
},
"footer_show_time": {
"type": "boolean",
"description": "Whether the footer should display the generation time",
"default": true
},
"allow_html_description": {
"type": "boolean",
"default": false,
"description": "[Deprecated]"
},
"minify": {
"type": "boolean",
"default": true,
"description": "[Deprecated]"
},
"templates_directory": {
"type": "string",
"description": "[Deprecated]"
}
}
}