Skip to content

Latest commit

 

History

History
461 lines (341 loc) · 36.3 KB

Configuration.md

File metadata and controls

461 lines (341 loc) · 36.3 KB

JSON Schema for Humans configuration file

Title: JSON Schema for Humans configuration file
Type object
Required No
Additional properties Any type allowed

Description: Choose how to generate JSON Schema for Humans documentation file.

Configuration parameters can be provided in several ways:

  • On the CLI using --config parameter_name=value (example: --config template_name=flat)
  • On the CLI using a config file --config-file config.json
  • From code, by providing a GenerationConfiguration object to the called generation method.
Property Pattern Type Deprecated Definition Title/Description
- description_is_markdown No boolean No - (HTML outputs only)
Whether to consider the description as Markdown and render it accordingly.
- description_safe_mode No enum (of null or string) No - (HTML outputs only)
(Only used with `description_is_markdown`)
How are HTML tags in descriptions handled. Correspond to the `safe_mode` option of the markdown2 library.

- "escape": Escape all HTML tags in descriptions
- "replace": Replace HTML tags with `[HTML_REMOVED]`
- null: Allow HTML in descriptions
- expand_buttons No boolean No - Add an `Expand all` and a `Collapse all` button at the top of the generated documentation.
- show_breadcrumbs No boolean No - For each property, show the relative place of that property in the schema.
- collapse_long_descriptions No boolean No - If a description is considered big, show only the beginning and add a `Read more` button.
- collapse_long_examples No boolean No - If an example is considered big, collapse it, it can be displayed with a `Show` option.
- link_to_reused_ref No boolean No - 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.

Note: If this option is off and the schema contains recursive definitions, the generation will crash!
- recursive_detection_depth No integer No - Advanced option
If `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.

This option determines the number of times to recursively follow definitions looking for a circular reference.

In other words, if a schema has a deeply nested element that refers to itself, this option may need to be increased.
- deprecated_from_description No boolean No - Mark a property as deprecated (with a big red badge) if the description contains the string `[​Deprecated`.
- default_from_description No boolean No - Extract the default value of a property from the description like this: ``[Default `the_default_value`]``.

The default value from the "default" attribute will be used in priority.
- copy_css No boolean No - Copy `schema_doc.css` to the same directory as `RESULT_FILE` after generation.
- copy_js No boolean No - Copy `schema_doc.min.js` to the same directory as `RESULT_FILE` after generation.

This file contains the logic for the anchor links.
- template_name No enum (of string) No - The name of the built-in template to use to render the documentation.

`js` is the default and uses javascript for anchor links, collapsible sections and tabs.

`js_offline` is identical to `js` except that all CSS, fonts and JavaScript are bundled for offline use.

`flat` uses no javascript, but has no interactivity.

`md` is the markdown template.

`md_nested` is the markdown template with collapsible nested sections.
- custom_template_path No string No - Path to a custom Jinja2 template file.

There can be multiple files to split the template, but this path should be the entry point.

If 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 No boolean No - Whether to render table of contents.
- examples_as_yaml No boolean No - Whether to display examples as YAML instead of JSON
- old_anchor_links No boolean No - Generate HTML ids for anchor links without special characters (keep only letters, digits, `_`, and `-`).

This is the old behaviour and is only needed for browsers that do not support HTML 5.
- markdown_options No object No - (Only used with `description_is_markdown`)
Markdown 2 options for the descriptions.
- template_md_options No object No - specific options to md template
- with_footer No boolean No - Whether to show the footer linking to the library repo and with the generation datetime
- footer_show_time No boolean No - Whether the footer should display the generation time
- allow_html_description No boolean Deprecated - [Deprecated]
- minify No boolean Deprecated - [Deprecated]
- templates_directory No string Deprecated - [Deprecated]

1. Property JSON Schema for Humans configuration file > description_is_markdown
Type boolean
Required No
Default true

Description: (HTML outputs only) Whether to consider the description as Markdown and render it accordingly.

2. Property JSON Schema for Humans configuration file > description_safe_mode
Type enum (of null or string)
Required No
Default "escape"

Description: (HTML outputs only) (Only used with description_is_markdown) How are HTML tags in descriptions handled. Correspond to the safe_mode option of the markdown2 library.

  • "escape": Escape all HTML tags in descriptions
  • "replace": Replace HTML tags with [HTML_REMOVED]
  • null: Allow HTML in descriptions

Must be one of:

  • null
  • "escape"
  • "replace"

3. Property JSON Schema for Humans configuration file > expand_buttons
Type boolean
Required No
Default false

Description: Add an Expand all and a Collapse all button at the top of the generated documentation.

4. Property JSON Schema for Humans configuration file > show_breadcrumbs
Type boolean
Required No
Default true

Description: For each property, show the relative place of that property in the schema.

5. Property JSON Schema for Humans configuration file > collapse_long_descriptions
Type boolean
Required No
Default true

Description: If a description is considered big, show only the beginning and add a Read more button.

6. Property JSON Schema for Humans configuration file > collapse_long_examples
Type boolean
Required No
Default true

Description: If an example is considered big, collapse it, it can be displayed with a Show option.

7. Property JSON Schema for Humans configuration file > link_to_reused_ref
Type boolean
Required No
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.

Note: If this option is off and the schema contains recursive definitions, the generation will crash!

8. Property JSON Schema for Humans configuration file > recursive_detection_depth
Type integer
Required No
Default 25

Description: Advanced option If 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.

This option determines the number of times to recursively follow definitions looking for a circular reference.

In other words, if a schema has a deeply nested element that refers to itself, this option may need to be increased.

9. Property JSON Schema for Humans configuration file > deprecated_from_description
Type boolean
Required No
Default false

Description: Mark a property as deprecated (with a big red badge) if the description contains the string [​Deprecated.

10. Property JSON Schema for Humans configuration file > default_from_description
Type boolean
Required No
Default false

Description: Extract the default value of a property from the description like this: [Default `the_default_value`].

The default value from the "default" attribute will be used in priority.

11. Property JSON Schema for Humans configuration file > copy_css
Type boolean
Required No
Default true

Description: Copy schema_doc.css to the same directory as RESULT_FILE after generation.

12. Property JSON Schema for Humans configuration file > copy_js
Type boolean
Required No
Default true

Description: Copy schema_doc.min.js to the same directory as RESULT_FILE after generation.

This file contains the logic for the anchor links.

13. Property JSON Schema for Humans configuration file > template_name
Type enum (of string)
Required No
Default "js"

Description: The name of the built-in template to use to render the documentation.

js is the default and uses javascript for anchor links, collapsible sections and tabs.

js_offline is identical to js except that all CSS, fonts and JavaScript are bundled for offline use.

flat uses no javascript, but has no interactivity.

md is the markdown template.

md_nested is the markdown template with collapsible nested sections.

Must be one of:

  • "flat"
  • "js"
  • "js_offline"
  • "md"
  • "md_nested"

14. Property JSON Schema for Humans configuration file > custom_template_path
Type string
Required No
Default null

Description: Path to a custom Jinja2 template file.

There can be multiple files to split the template, but this path should be the entry point.

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

15. Property JSON Schema for Humans configuration file > show_toc
Type boolean
Required No
Default true

Description: Whether to render table of contents.

16. Property JSON Schema for Humans configuration file > examples_as_yaml
Type boolean
Required No
Default false

Description: Whether to display examples as YAML instead of JSON

17. Property JSON Schema for Humans configuration file > old_anchor_links
Type boolean
Required No
Default false

Description: Generate HTML ids for anchor links without special characters (keep only letters, digits, _, and -).

This is the old behaviour and is only needed for browsers that do not support HTML 5.

18. Property JSON Schema for Humans configuration file > markdown_options
Type object
Required No
Additional properties Any type allowed
Default {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}

Description: (Only used with description_is_markdown) Markdown 2 options for the descriptions.

Example:

{
    "fenced-code-blocks": {
        "cssclass": "highlight jumbotron"
    },
    "tables": null,
    "break-on-newline": true,
    "cuddled-lists": true
}

19. Property JSON Schema for Humans configuration file > template_md_options
Type object
Required No
Additional properties Any type allowed

Description: specific options to md template

Property Pattern Type Deprecated Definition Title/Description
- badge_as_image No boolean No - if true generate badges(eg: optional, required) using embedded image (https://img.shields.io).

if false, use text instead
- show_heading_numbers No boolean No - if true generate heading numbers to correspond to table of contents.

if false, do not generate heading numbers
- show_array_restrictions No boolean No - if true generate array restrictions section.

if false, do not generate
- properties_table_columns No array of enum (of string) No - array of column names to display in the properties table.

if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description']

19.1. Property JSON Schema for Humans configuration file > template_md_options > badge_as_image
Type boolean
Required No
Default false

Description: if true generate badges(eg: optional, required) using embedded image (https://img.shields.io).

if false, use text instead

19.2. Property JSON Schema for Humans configuration file > template_md_options > show_heading_numbers
Type boolean
Required No
Default true

Description: if true generate heading numbers to correspond to table of contents.

if false, do not generate heading numbers

19.3. Property JSON Schema for Humans configuration file > template_md_options > show_array_restrictions
Type boolean
Required No
Default true

Description: if true generate array restrictions section.

if false, do not generate

19.4. Property JSON Schema for Humans configuration file > template_md_options > properties_table_columns
Type array of enum (of string)
Required No

Description: array of column names to display in the properties table.

if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description']

Array restrictions
Min items N/A
Max items N/A
Items unicity False
Additional items False
Tuple validation See below
Each item of this array must be Description
properties_table_columns items -

19.4.1. JSON Schema for Humans configuration file > template_md_options > properties_table_columns > properties_table_columns items
Type enum (of string)
Required No

Must be one of:

  • "Property"
  • "Pattern"
  • "Type"
  • "Deprecated"
  • "Definition"
  • "Title/Description"

20. Property JSON Schema for Humans configuration file > with_footer
Type boolean
Required No
Default true

Description: Whether to show the footer linking to the library repo and with the generation datetime

21. Property JSON Schema for Humans configuration file > footer_show_time
Type boolean
Required No
Default true

Description: Whether the footer should display the generation time

22. ~~ Property JSON Schema for Humans configuration file > allow_html_description~~
Type boolean
Required No
Deprecated
Default false

Description: [Deprecated]

23. ~~ Property JSON Schema for Humans configuration file > minify~~
Type boolean
Required No
Deprecated
Default true

Description: [Deprecated]

24. ~~ Property JSON Schema for Humans configuration file > templates_directory~~
Type string
Required No
Deprecated

Description: [Deprecated]

Generated using json-schema-for-humans