path: root/python-json-schema-for-humans.spec

%global _empty_manifest_terminate_build 0
Name:		python-json-schema-for-humans
Version:	0.44.4
Release:	1
Summary:	Generate static HTML documentation from JSON schemas
License:	Apache-2.0
URL:		https://github.com/coveooss/json-schema-for-humans
Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/32/ed/a9ff6cdb4aa8e2368b946b0edea2f5883a906829bcd3beaa3496eb50a38a/json-schema-for-humans-0.44.4.tar.gz
BuildArch:	noarch

Requires:	python3-click
Requires:	python3-dataclasses-json
Requires:	python3-htmlmin
Requires:	python3-Jinja2
Requires:	python3-markdown2
Requires:	python3-Pygments
Requires:	python3-pytz
Requires:	python3-PyYAML
Requires:	python3-requests
Requires:	python3-MarkupSafe

%description
generate_from_schema | `schema_file` as str or `pathlib.Path` | Rendered doc as a str | No
generate_from_filename | `schema_file_name` as str or `pathlib.Path` | Rendered doc written to the file at path `result_file_name` | Yes
generate_from_file_object | `schema_file` as an open file object (read mode) | Rendered doc written to the file at `result_file`, which must be an open file object (in write mode) | Yes
Notes:
- When using file objects, it is assumed that files are opened with encoding "utf-8"
- CSS and JS files are copied to the current working directory with names "schema_doc.css" and "schema_doc.min.js" respectively, if necessary
- Other parameters of these methods are analogous to the CLI parameters documented above.
#### The GenerationConfiguration object
To reduce the number of parameters to pass from function to function in the code, there is a `GenerationConfiguration` object that should be used for providing options.
Example:
```python
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration
config = GenerationConfiguration(copy_css=False, expand_buttons=True)
generate_from_filename("my_schema.json", "schema_doc.html", config=config)
# Your doc is now in a file named "schema_doc.html". Next to it, "schema_doc.min.js" was copied, but not "schema_doc.css"
# Your doc will contain a "Expand all" and a "Collapse all" button at the top
```
#### Pre-load schemas
`generate_from_schema` has a `loaded_schemas` parameter that can be used to pre-load schemas. This must be a dict with the key being the real path of the schema file and the value being the result of loading the schema (with `json.load` or `yaml.safe_load`, for example).
This should not be necessary in normal scenarios.
## What's supported
See the excellent [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/index.html) to understand what are those checks
The following are supported:
- Types
- Regular expressions
- String length
- String format
- Numeric types multiples and range
- Constant and enumerated values
- Required properties
- Pattern properties
- Default values
- Array `minItems`, `maxItems`, `uniqueItems`, `items`, `prefixItems`, and `contains`
- Combining schema with `oneOf`, `allOf`, `anyOf`, and `not`
- Examples
- Conditional subschemas
These are **not** supported at the moment (PRs welcome!):
- Property names and size
- Property dependencies
- Media
## References
References are supported:
- To another part of the schema, e.g. `{ $ref: "#/definitions/something" }`
- To a local file, `{"$ref": "references.json"}`, `{"$ref": "references.json#/definitions/something"}`
- To a URL, `{"$ref": "http://example.com/schema.json"}`, `{"$ref": "http://example.com/schema.json#/definitions/something"}`
You _can_ have a `description` next to a `$ref`, it will be displayed in priority to the description from the referenced element.
If you have several attributes using the same definition, the definition will only be rendered once.
All other usages of the same definition will be replaced with an anchor link to the first render of the definition.
This can be turned off using `--config no_link_to_reused_ref`. See `With references` in the examples.
## Templates
Templates control the style of the generated documentation.
### js
This is the default template. It uses Bootstrap along with minimal Javascript to allow for the following:
- Properties are in expandable dynamic sections. You can include a button to expand or collapse all. (See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#expand_buttons) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#expand_buttons))
- Conditional subschemas (`anyOf`, `oneOf`, `allOf`) are in tabbed sections
- Anchor links will scroll to, expand, and animate the target section 
- Long descriptions are collapsed by default
When using this template, you need to include the Javascript file (`schema_doc.min.js`) that is automatically copied next to the output HTML file (`schema_doc.html` by default).
### flat
*Note*: This template is a work in progress
It is sometimes not possible or desirable to include custom Javascript in documentation. This template addresses this issue by removing interactive elements in favor of simpler HTML.
At the moment, this means the whole documentation is generated without any collapsible sections, which may make it hard to understand the schema structure. Contributions are welcomed to improve it!
### MD (Markdown)
*Note*: This template is a work in progress
This template allows users to publish the generated documentation without hosting an HTTP server.
On GitHub, this format is rendered directly when browsing code.
A table of content is provided at the beginning of the file for easy navigation.
You can display some important information as badge using an option.
See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#template_md_options_badge_as_image) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#template_md_options_badge_as_image)
Contributions are welcomed to improve it!
## Contributing
[See CONTRIBUTING.md](CONTRIBUTING.md)

%package -n python3-json-schema-for-humans
Summary:	Generate static HTML documentation from JSON schemas
Provides:	python-json-schema-for-humans
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-json-schema-for-humans
generate_from_schema | `schema_file` as str or `pathlib.Path` | Rendered doc as a str | No
generate_from_filename | `schema_file_name` as str or `pathlib.Path` | Rendered doc written to the file at path `result_file_name` | Yes
generate_from_file_object | `schema_file` as an open file object (read mode) | Rendered doc written to the file at `result_file`, which must be an open file object (in write mode) | Yes
Notes:
- When using file objects, it is assumed that files are opened with encoding "utf-8"
- CSS and JS files are copied to the current working directory with names "schema_doc.css" and "schema_doc.min.js" respectively, if necessary
- Other parameters of these methods are analogous to the CLI parameters documented above.
#### The GenerationConfiguration object
To reduce the number of parameters to pass from function to function in the code, there is a `GenerationConfiguration` object that should be used for providing options.
Example:
```python
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration
config = GenerationConfiguration(copy_css=False, expand_buttons=True)
generate_from_filename("my_schema.json", "schema_doc.html", config=config)
# Your doc is now in a file named "schema_doc.html". Next to it, "schema_doc.min.js" was copied, but not "schema_doc.css"
# Your doc will contain a "Expand all" and a "Collapse all" button at the top
```
#### Pre-load schemas
`generate_from_schema` has a `loaded_schemas` parameter that can be used to pre-load schemas. This must be a dict with the key being the real path of the schema file and the value being the result of loading the schema (with `json.load` or `yaml.safe_load`, for example).
This should not be necessary in normal scenarios.
## What's supported
See the excellent [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/index.html) to understand what are those checks
The following are supported:
- Types
- Regular expressions
- String length
- String format
- Numeric types multiples and range
- Constant and enumerated values
- Required properties
- Pattern properties
- Default values
- Array `minItems`, `maxItems`, `uniqueItems`, `items`, `prefixItems`, and `contains`
- Combining schema with `oneOf`, `allOf`, `anyOf`, and `not`
- Examples
- Conditional subschemas
These are **not** supported at the moment (PRs welcome!):
- Property names and size
- Property dependencies
- Media
## References
References are supported:
- To another part of the schema, e.g. `{ $ref: "#/definitions/something" }`
- To a local file, `{"$ref": "references.json"}`, `{"$ref": "references.json#/definitions/something"}`
- To a URL, `{"$ref": "http://example.com/schema.json"}`, `{"$ref": "http://example.com/schema.json#/definitions/something"}`
You _can_ have a `description` next to a `$ref`, it will be displayed in priority to the description from the referenced element.
If you have several attributes using the same definition, the definition will only be rendered once.
All other usages of the same definition will be replaced with an anchor link to the first render of the definition.
This can be turned off using `--config no_link_to_reused_ref`. See `With references` in the examples.
## Templates
Templates control the style of the generated documentation.
### js
This is the default template. It uses Bootstrap along with minimal Javascript to allow for the following:
- Properties are in expandable dynamic sections. You can include a button to expand or collapse all. (See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#expand_buttons) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#expand_buttons))
- Conditional subschemas (`anyOf`, `oneOf`, `allOf`) are in tabbed sections
- Anchor links will scroll to, expand, and animate the target section 
- Long descriptions are collapsed by default
When using this template, you need to include the Javascript file (`schema_doc.min.js`) that is automatically copied next to the output HTML file (`schema_doc.html` by default).
### flat
*Note*: This template is a work in progress
It is sometimes not possible or desirable to include custom Javascript in documentation. This template addresses this issue by removing interactive elements in favor of simpler HTML.
At the moment, this means the whole documentation is generated without any collapsible sections, which may make it hard to understand the schema structure. Contributions are welcomed to improve it!
### MD (Markdown)
*Note*: This template is a work in progress
This template allows users to publish the generated documentation without hosting an HTTP server.
On GitHub, this format is rendered directly when browsing code.
A table of content is provided at the beginning of the file for easy navigation.
You can display some important information as badge using an option.
See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#template_md_options_badge_as_image) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#template_md_options_badge_as_image)
Contributions are welcomed to improve it!
## Contributing
[See CONTRIBUTING.md](CONTRIBUTING.md)

%package help
Summary:	Development documents and examples for json-schema-for-humans
Provides:	python3-json-schema-for-humans-doc
%description help
generate_from_schema | `schema_file` as str or `pathlib.Path` | Rendered doc as a str | No
generate_from_filename | `schema_file_name` as str or `pathlib.Path` | Rendered doc written to the file at path `result_file_name` | Yes
generate_from_file_object | `schema_file` as an open file object (read mode) | Rendered doc written to the file at `result_file`, which must be an open file object (in write mode) | Yes
Notes:
- When using file objects, it is assumed that files are opened with encoding "utf-8"
- CSS and JS files are copied to the current working directory with names "schema_doc.css" and "schema_doc.min.js" respectively, if necessary
- Other parameters of these methods are analogous to the CLI parameters documented above.
#### The GenerationConfiguration object
To reduce the number of parameters to pass from function to function in the code, there is a `GenerationConfiguration` object that should be used for providing options.
Example:
```python
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration
config = GenerationConfiguration(copy_css=False, expand_buttons=True)
generate_from_filename("my_schema.json", "schema_doc.html", config=config)
# Your doc is now in a file named "schema_doc.html". Next to it, "schema_doc.min.js" was copied, but not "schema_doc.css"
# Your doc will contain a "Expand all" and a "Collapse all" button at the top
```
#### Pre-load schemas
`generate_from_schema` has a `loaded_schemas` parameter that can be used to pre-load schemas. This must be a dict with the key being the real path of the schema file and the value being the result of loading the schema (with `json.load` or `yaml.safe_load`, for example).
This should not be necessary in normal scenarios.
## What's supported
See the excellent [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/index.html) to understand what are those checks
The following are supported:
- Types
- Regular expressions
- String length
- String format
- Numeric types multiples and range
- Constant and enumerated values
- Required properties
- Pattern properties
- Default values
- Array `minItems`, `maxItems`, `uniqueItems`, `items`, `prefixItems`, and `contains`
- Combining schema with `oneOf`, `allOf`, `anyOf`, and `not`
- Examples
- Conditional subschemas
These are **not** supported at the moment (PRs welcome!):
- Property names and size
- Property dependencies
- Media
## References
References are supported:
- To another part of the schema, e.g. `{ $ref: "#/definitions/something" }`
- To a local file, `{"$ref": "references.json"}`, `{"$ref": "references.json#/definitions/something"}`
- To a URL, `{"$ref": "http://example.com/schema.json"}`, `{"$ref": "http://example.com/schema.json#/definitions/something"}`
You _can_ have a `description` next to a `$ref`, it will be displayed in priority to the description from the referenced element.
If you have several attributes using the same definition, the definition will only be rendered once.
All other usages of the same definition will be replaced with an anchor link to the first render of the definition.
This can be turned off using `--config no_link_to_reused_ref`. See `With references` in the examples.
## Templates
Templates control the style of the generated documentation.
### js
This is the default template. It uses Bootstrap along with minimal Javascript to allow for the following:
- Properties are in expandable dynamic sections. You can include a button to expand or collapse all. (See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#expand_buttons) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#expand_buttons))
- Conditional subschemas (`anyOf`, `oneOf`, `allOf`) are in tabbed sections
- Anchor links will scroll to, expand, and animate the target section 
- Long descriptions are collapsed by default
When using this template, you need to include the Javascript file (`schema_doc.min.js`) that is automatically copied next to the output HTML file (`schema_doc.html` by default).
### flat
*Note*: This template is a work in progress
It is sometimes not possible or desirable to include custom Javascript in documentation. This template addresses this issue by removing interactive elements in favor of simpler HTML.
At the moment, this means the whole documentation is generated without any collapsible sections, which may make it hard to understand the schema structure. Contributions are welcomed to improve it!
### MD (Markdown)
*Note*: This template is a work in progress
This template allows users to publish the generated documentation without hosting an HTTP server.
On GitHub, this format is rendered directly when browsing code.
A table of content is provided at the beginning of the file for easy navigation.
You can display some important information as badge using an option.
See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/Configuration.html#template_md_options_badge_as_image) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#template_md_options_badge_as_image)
Contributions are welcomed to improve it!
## Contributing
[See CONTRIBUTING.md](CONTRIBUTING.md)

%prep
%autosetup -n json-schema-for-humans-0.44.4

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-json-schema-for-humans -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Sun Apr 23 2023 Python_Bot <Python_Bot@openeuler.org> - 0.44.4-1
- Package Spec generated