diff --git a/README.md b/README.md index c3fa62e..4f73e5f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -# mkdocs schema reader plugin +# mkdocs schema reader plugin This is a plugin that scans the specified directories and files for JSON Schema files, converts them to markdown and builds them into your documentation. +**Breaking Change** This version can introduce some breaking change. Markdown output is now wrtie to documentation directory (`${docs_dir/schema}`)instead of `site/schema`. If your documentation was in `site` folder, this will change nothing. Use the new `output` options for control it if needed. + ## Setup Install the plugin using pip: @@ -20,7 +22,7 @@ Then, specify folders and files that you want to include in `mkdocs.yml` relativ plugins: - search - schema_reader: - include: + include: - "../JSONSchema/" - "../example/directory/schema.json" ``` @@ -34,3 +36,36 @@ More information about plugins in the [MkDocs documentation][mkdocs-plugins]. ## Usage Just activate the plugin, specify directories and files in the manner shown above, and it will operate when normal mkdocs commands are used like `mkdocs serve' + +## Options + +- `auto_nav` : If true, generated markdown from JSON will be add to navigation path. Using `nav` (default `Schema`) entry (bool, default=True) +- `output` : Set export directory for markdown file, directory relative to `docs_dir` (str, default="/schema") +- `nav` : Set the navigation path when JSON schema will be find in web IHM (str, default="Schema"). Can be a complexe path (like /home/json/schema), but, it will not merge if existing path already exist *see note*. +- `example_as_yaml` : Show example as yaml instead of json (bool, default=False) +- `show_example` : Select what example will be show (str, default='all') + - `all` : All examples + - `object` : Only examples present in objects section + - `propertie` : Only examples present in properties section + +> **Notes** About `nav` : Nav path is adding to navigation without merge with existing path. If you want to show schema in existing section (referenced in classic nav), set `auto_nav` to false and refere it by yourself in classic nav. +> Example : +> +> ```yaml +> plugins: +> - search +> - schema_reader: +> include: ## Relative to mkdocs.yaml file +> - "documentations/configuration/schemas/my_schema01.json" +> - "documentations/configuration/schemas/my_schema02.json" +> auto_nav: false +> output: "configuration/schemas/docs" +> example_as_yaml: true +> show_example: object +> nav: +> - Home: index.md +> - Config: +> - About: configuration/about.md +> - Schema 01: configuration/schemas/docs/my_schema01.md +> - Schema 02: configuration/schemas/docs/my_schema02.md +> ``` diff --git a/mkdocs_schema_reader/schema_reader.py b/mkdocs_schema_reader/schema_reader.py index d728cd4..8fc6963 100644 --- a/mkdocs_schema_reader/schema_reader.py +++ b/mkdocs_schema_reader/schema_reader.py @@ -10,7 +10,14 @@ class SchemaReader(BasePlugin): - config_scheme = (("include", config_options.Type(list, default=[])),) + config_scheme = ( + ("include", config_options.Type(list, default=[])), + ("auto_nav", config_options.Type(bool, default=True)), + ("output", config_options.Type(str, default="schema")), + ("nav", config_options.Type(str, default="Schema")), + ("example_as_yaml", config_options.Type(bool, default=False)), + ("show_example", config_options.Type(str, default='all')) + ) def on_files(self, files, config): # Add json files within included files/directories to list @@ -29,9 +36,20 @@ def on_files(self, files, config): else: logging.warning(f"Could not locate {entry}") - parser = jsonschema2md.Parser() + parser = jsonschema2md.Parser( + examples_as_yaml=self.config["example_as_yaml"], + show_examples=self.config["show_example"] + ) schema_list = [] - schema_dict = {"Schema": schema_list} + + ## Path to Nav ## + path=list(filter(None, self.config["nav"].split('/'))) + path.reverse() + out_as_string = f"{{'{path.pop(0)}': schema_list}}" + for item in path: + out_as_string = f"{{'{item}':[{out_as_string}]}}" + + schema_dict = eval(f"{out_as_string}") for filepath in locations: file = os.path.basename(filepath) @@ -42,10 +60,10 @@ def on_files(self, files, config): schema_syntax = ["$schema", "$ref"] if any(x in data for x in schema_syntax): + path = f"{config['docs_dir']}/{self.config['output']}/{file[:-5]}.md" # write converted markdown file to this location - path = f"site/schema/{file[:-5]}.md" - if not os.path.isdir("./site/schema"): - os.makedirs("./site/schema", exist_ok=True) + if not os.path.isdir(f"{config['docs_dir']}/{self.config['output']}"): + os.makedirs(f"{config['docs_dir']}/{self.config['output']}", exist_ok=True) try: with open(path, "w") as md: @@ -61,8 +79,8 @@ def on_files(self, files, config): # Add to Files object mkdfile = File( - f"schema/{file[:-5]}.md", - f"{os.getcwd()}/site", + f"{self.config['output']}/{file[:-5]}.md", + config['docs_dir'], config["site_dir"], config["use_directory_urls"], ) @@ -77,6 +95,7 @@ def on_files(self, files, config): ) # Add schemas to nav - config["nav"].append(schema_dict) + if self.config["auto_nav"]: + config["nav"].append(schema_dict) - return files + return files \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index afe0907..4ade5f0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,2 @@ -mkdocs==1.0.3 -jsonschema2md +mkdocs>=1.0.3 +jsonschema2md>=0.3.0 diff --git a/setup.py b/setup.py index d79e22c..381022c 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ setup( name="mkdocs_schema_reader", - version="0.11.1", + version="0.12.1", description="A MkDocs plugin to collate json schema files and convert them into markdown files", long_description=long_description, long_description_content_type="text/markdown", @@ -16,7 +16,7 @@ author_email="tome.robin@gmail.com", license="MIT", python_requires=">=3.6", - install_requires=["mkdocs>=1.0.4", "jsonschema2md"], + install_requires=["mkdocs>=1.0.4", "jsonschema2md>=0.3.0"], packages=find_packages(), entry_points={ "mkdocs.plugins": [