From c0c9d09e00427786dc571d4cd71b7c36c80dc811 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Fri, 29 Nov 2024 20:49:28 +0100 Subject: [PATCH] fix: Fix markdown "break on newline" configurability (#236) Previously, `"break-on-newline": True` was part of the default markdown options. The user could override the configuration value, thus turning it into `"break-on-newline": False`, but unfortunately the markdown2 library ignores the value of the option, and always sets it to `True` if the key is passed in. The `break-on-newline` extra is deprecated, there is a new option since 2.4.11: `breaks` https://github.com/trentm/python-markdown2/wiki/breaks Unfortunately, markdown2 overrides the `breaks.on_newline` configuration if `break-on-newline` is present in the extras, meaning that this doesn't work for disabling "break on newline" either. This means that right now there is _no_ way for the users of jsfh to disable line breaks on newlines. To fix this, remove `break-on-newline` from the default markdown options. If (and only if) the `breaks` config is _not_ set by the user, a `breaks` config is added to the defaults that inserts line breaks on newlines by default. --------- Co-authored-by: Denis Blanchette --- config_schema.json | 4 ++-- .../examples_flat_default/Configuration.html | 8 +++----- .../examples_js_default/Configuration.html | 17 ++++------------ .../Configuration.html | 17 ++++------------ .../examples_md_default/Configuration.md | 20 +++++++++---------- .../Configuration.md | 20 +++++++++---------- .../Configuration.md | 18 ++++++++--------- .../examples_md_with_badges/Configuration.md | 18 ++++++++--------- .../generation_configuration.py | 11 +++++++--- tests/generation_configuration_test.py | 15 ++++++++------ 10 files changed, 64 insertions(+), 84 deletions(-) diff --git a/config_schema.json b/config_schema.json index fb30d958..7176a87c 100644 --- a/config_schema.json +++ b/config_schema.json @@ -103,9 +103,9 @@ "cssclass": "highlight jumbotron" }, "tables": null, - "break-on-newline": true + "breaks": {"on_newline": true, "on_backslash": true} }, - "description": "[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. `description_is_markdown` must be true for this to have any effect.\n\n**WARNING**\nAdding an extra, even if the value is false, will activate it. For example `{\"break-on-newline\": false}` will activate the `break-on-newline` extra.", + "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": { diff --git a/docs/examples/examples_flat_default/Configuration.html b/docs/examples/examples_flat_default/Configuration.html index 78157d51..ae40f57c 100644 --- a/docs/examples/examples_flat_default/Configuration.html +++ b/docs/examples/examples_flat_default/Configuration.html @@ -745,7 +745,7 @@

d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z" /> - markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}
+ markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}
@@ -753,10 +753,8 @@

-

Markdown 2 options for the descriptions. description_is_markdown must be true for this to have any effect.

- -

WARNING
-Adding an extra, even if the value is false, will activate it. For example {"break-on-newline": false} will activate the break-on-newline extra.

+

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

diff --git a/docs/examples/examples_js_default/Configuration.html b/docs/examples/examples_js_default/Configuration.html index 13f542dc..1bbfb341 100644 --- a/docs/examples/examples_js_default/Configuration.html +++ b/docs/examples/examples_js_default/Configuration.html @@ -720,19 +720,10 @@

d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z" /> - markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}
-
-

Markdown 2 options for the descriptions. description_is_markdown must be true for this to have any effect.

- -

WARNING
-Adding an extra, even if the value is false, will activate it. For example {"break-on-newline": false} will activate the break-on-newline extra.

- -
-
- -
+ markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}
+

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

+ diff --git a/docs/examples/examples_js_offline_default/Configuration.html b/docs/examples/examples_js_offline_default/Configuration.html index 1abd9bd6..eeff173f 100644 --- a/docs/examples/examples_js_offline_default/Configuration.html +++ b/docs/examples/examples_js_offline_default/Configuration.html @@ -720,19 +720,10 @@

d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z" /> - markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}
-
-

Markdown 2 options for the descriptions. description_is_markdown must be true for this to have any effect.

- -

WARNING
-Adding an extra, even if the value is false, will activate it. For example {"break-on-newline": false} will activate the break-on-newline extra.

- -
-
- -
+ markdown_optionsType: object Default: {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}
+

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

+ diff --git a/docs/examples/examples_md_default/Configuration.md b/docs/examples/examples_md_default/Configuration.md index 881b4d9d..d0f93323 100644 --- a/docs/examples/examples_md_default/Configuration.md +++ b/docs/examples/examples_md_default/Configuration.md @@ -65,7 +65,7 @@ Configuration parameters can be provided in several ways: | - [show_toc](#show_toc ) | No | boolean | No | - | Whether to render table of contents. | | - [examples_as_yaml](#examples_as_yaml ) | No | boolean | No | - | Whether to display examples as YAML instead of JSON | | - [old_anchor_links](#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](#markdown_options ) | No | object | No | - | [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. \`description_is_markdown\` must be true for this to have any effect.

**WARNING**
Adding an extra, even if the value is false, will activate it. For example \`{"break-on-newline": false}\` will activate the \`break-on-newline\` extra. | +| - [markdown_options](#markdown_options ) | No | object | No | - | (Only used with \`description_is_markdown\`)
[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. | | - [template_md_options](#template_md_options ) | No | object | No | - | specific options to md template | | - [with_footer](#with_footer ) | No | boolean | No | - | Whether to show the footer linking to the library repo and with the generation datetime | | - [footer_show_time](#footer_show_time ) | No | boolean | No | - | Whether the footer should display the generation time | @@ -291,17 +291,15 @@ This is the old behaviour and is only needed for browsers that do not support HT ## 18. Property `JSON Schema for Humans configuration file > markdown_options` -| | | -| ------------------------- | ------------------------------------------------------------------------------------------------------- | -| **Type** | `object` | -| **Required** | No | -| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | -| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}` | +| | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | +| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}` | -**Description:** [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. `description_is_markdown` must be true for this to have any effect. - -**WARNING** -Adding an extra, even if the value is false, will activate it. For example `{"break-on-newline": false}` will activate the `break-on-newline` extra. +**Description:** (Only used with `description_is_markdown`) +[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. **Example:** diff --git a/docs/examples/examples_md_nested_default/Configuration.md b/docs/examples/examples_md_nested_default/Configuration.md index 2666f652..872b569b 100644 --- a/docs/examples/examples_md_nested_default/Configuration.md +++ b/docs/examples/examples_md_nested_default/Configuration.md @@ -405,17 +405,15 @@ This is the old behaviour and is only needed for browsers that do not support HT
-| | | -| ------------------------- | ------------------------------------------------------------------------------------------------------- | -| **Type** | `object` | -| **Required** | No | -| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | -| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}` | - -**Description:** [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. `description_is_markdown` must be true for this to have any effect. - -**WARNING** -Adding an extra, even if the value is false, will activate it. For example `{"break-on-newline": false}` will activate the `break-on-newline` extra. +| | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are 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](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. **Example:** diff --git a/docs/examples/examples_md_nested_with_badges/Configuration.md b/docs/examples/examples_md_nested_with_badges/Configuration.md index 0f4786b0..5196c998 100644 --- a/docs/examples/examples_md_nested_with_badges/Configuration.md +++ b/docs/examples/examples_md_nested_with_badges/Configuration.md @@ -387,16 +387,14 @@ This is the old behaviour and is only needed for browsers that do not support HT
-| | | -| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **Type** | `object` | -| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | -| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}` | - -**Description:** [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. `description_is_markdown` must be true for this to have any effect. - -**WARNING** -Adding an extra, even if the value is false, will activate it. For example `{"break-on-newline": false}` will activate the `break-on-newline` extra. +| | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Type** | `object` | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are 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](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. **Example:** diff --git a/docs/examples/examples_md_with_badges/Configuration.md b/docs/examples/examples_md_with_badges/Configuration.md index 0ea67ae8..e21d608b 100644 --- a/docs/examples/examples_md_with_badges/Configuration.md +++ b/docs/examples/examples_md_with_badges/Configuration.md @@ -64,7 +64,7 @@ Configuration parameters can be provided in several ways: | - [show_toc](#show_toc ) | No | boolean | No | - | Whether to render table of contents. | | - [examples_as_yaml](#examples_as_yaml ) | No | boolean | No | - | Whether to display examples as YAML instead of JSON | | - [old_anchor_links](#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](#markdown_options ) | No | object | No | - | [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. \`description_is_markdown\` must be true for this to have any effect.

**WARNING**
Adding an extra, even if the value is false, will activate it. For example \`{"break-on-newline": false}\` will activate the \`break-on-newline\` extra. | +| - [markdown_options](#markdown_options ) | No | object | No | - | (Only used with \`description_is_markdown\`)
[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. | | - [template_md_options](#template_md_options ) | No | object | No | - | specific options to md template | | - [with_footer](#with_footer ) | No | boolean | No | - | Whether to show the footer linking to the library repo and with the generation datetime | | - [footer_show_time](#footer_show_time ) | No | boolean | No | - | Whether the footer should display the generation time | @@ -273,16 +273,14 @@ This is the old behaviour and is only needed for browsers that do not support HT ## 18. ![Optional](https://img.shields.io/badge/Optional-yellow) Property `JSON Schema for Humans configuration file > markdown_options` -| | | -| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **Type** | `object` | -| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | -| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "break-on-newline": true}` | - -**Description:** [Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. `description_is_markdown` must be true for this to have any effect. +| | | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Type** | `object` | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Default** | `{"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}}` | -**WARNING** -Adding an extra, even if the value is false, will activate it. For example `{"break-on-newline": false}` will activate the `break-on-newline` extra. +**Description:** (Only used with `description_is_markdown`) +[Markdown 2 options](https://github.com/trentm/python-markdown2/wiki/Extras) for the descriptions. **Example:** diff --git a/json_schema_for_humans/generation_configuration.py b/json_schema_for_humans/generation_configuration.py index 759684c1..1031eede 100644 --- a/json_schema_for_humans/generation_configuration.py +++ b/json_schema_for_humans/generation_configuration.py @@ -61,12 +61,17 @@ class GenerationConfiguration: footer_show_time: bool = True def __post_init__(self) -> None: - default_markdown_options = { - "break-on-newline": True, + self.markdown_options = self.markdown_options or {} + default_markdown_options: Dict[str, Any] = { "fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": None, } - default_markdown_options.update(self.markdown_options or {}) + if "breaks" not in self.markdown_options: + default_markdown_options["breaks"] = { + "on_newline": True, + "on_backslash": True, + } + default_markdown_options.update(self.markdown_options) self.markdown_options = default_markdown_options default_template_md_options = { diff --git a/tests/generation_configuration_test.py b/tests/generation_configuration_test.py index 2f3835a3..6f7b0afd 100644 --- a/tests/generation_configuration_test.py +++ b/tests/generation_configuration_test.py @@ -6,7 +6,10 @@ def test_default_values() -> None: """Test init GenerationConfiguration with default values""" config = GenerationConfiguration() assert config.markdown_options == { - "break-on-newline": True, + "breaks": { + "on_newline": True, + "on_backslash": True, + }, "fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": None, } @@ -18,9 +21,9 @@ def test_override_markdown_options() -> None: """Test init GenerationConfiguration with default values""" # override break-on-newline key - config = GenerationConfiguration(markdown_options={"break-on-newline": False}) + config = GenerationConfiguration(markdown_options={"breaks": {"on_newline": False}}) assert config.markdown_options == { - "break-on-newline": False, + "breaks": {"on_newline": False}, "fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": None, } @@ -31,14 +34,14 @@ def test_override_markdown_options() -> None: } ) assert config.markdown_options == { - "break-on-newline": True, + "breaks": {"on_newline": True, "on_backslash": True}, "fenced-code-blocks": {"cssclass": "test"}, "tables": None, } # override tables key config = GenerationConfiguration(markdown_options={"tables": ["test"]}) assert config.markdown_options == { - "break-on-newline": True, + "breaks": {"on_newline": True, "on_backslash": True}, "fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": ["test"], } @@ -46,7 +49,7 @@ def test_override_markdown_options() -> None: # add a new key config = GenerationConfiguration(markdown_options={"newKey": "test"}) assert config.markdown_options == { - "break-on-newline": True, + "breaks": {"on_newline": True, "on_backslash": True}, "fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": None, "newKey": "test",