docsification

coveooss · Apr 17, 2021 · c3b9f46 · c3b9f46
1 parent 29acddd
commit c3b9f46
Show file tree

Hide file tree

Showing 12 changed files with 902 additions and 293 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,22 +1,29 @@
+# Contributing 
+
 Contributions are more than welcome! Don't hesitate to open an incomplete PR to ask for help!
 
-# Python versions
+## Python versions
 
 The library currently supports Python versions 3.6+
 
-# Testing
+## install dependencies
+Just run 
+
+`pip3 install -r requirements.txt`
+
+## Testing
 
-## With Tox
+### With Tox
 Just run tox
 
 `tox`
 
-## With pytest directly
+### With pytest directly
 `python -m pytest tests`
 
 (Or `python3 -m pytest tests` if you still have Python 2 (e.g.: Ubuntu))
 
-# Adding a new template
+## Adding a new template
 
 Just copy one of the existing template, change the name and start modifying.
 If you are looking for examples, you can run `python3 docs/generate_examples.py` from the root folder.
@@ -27,30 +34,30 @@ The examples will be in:
 * `docs/examples/examples_md_default`
 * `docs/examples/examples_js_with_bagdes`
 
-# Optional stuff
+## Optional stuff
 The maintainer will take care of the following for you if you don't want to bother with it :)
 
-## Formatting with black
+### Formatting with black
 Running with tox will ensure the code has been formatted with [black](https://github.com/psf/black)
 
 It is recommended to run black [from your IDE](https://github.com/psf/black/blob/master/docs/editor_integration.md) or as a pre-commit hook
 
-## Modifying Javascript
+### Modifying Javascript
 `schema_doc.js` is not minified automatically, you are responsible for doing it yourself
 
-## Generating doc
+### Generating doc
 The documentation is served by `index.html` deployed on GitHub Pages automatically.
 The documentation is using [docsify](https://docsify.js.org/) to render.
 
-### Adding examples
+#### Adding examples
 
 - Run `python docs/generate_examples.py`. This will get all examples from `docs/examples/cases`, render the resulting HTML and
  include it in the appropriate folders.
 - (optional) If you have added an example, add the file name (without `.json`), the display name and description in `docs/cases_description.yaml`
 
-### Generating locally
+#### Generating locally
 
-#### Linux
+##### Linux
 Execute following script from root dir of the repository
 ```bash
 python3 docs/generate_examples.py

diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -1,11 +1,11 @@
 Copyright 2019 Coveo Solutions Inc.
- 
+
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
- 
+
     http://www.apache.org/licenses/LICENSE-2.0
- 
+
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # JSON Schema for Humans
 
-Quickly generate a beautiful static page documenting a JSON schema
+Quickly generate a beautiful static HTML or Markdown page documenting a JSON schema
 
 [Documentation (with visual examples)](https://coveooss.github.io/json-schema-for-humans)
 
@@ -11,7 +11,7 @@ Quickly generate a beautiful static page documenting a JSON schema
 - Support for JSON Schema Draft-07
 - Since the result is static, it is easier to host and faster to load
 - HTML and Markdown output support
-- Different templates to choose from. More details: [HTML version](https://coveooss.github.io/json-schema-for-humans/assets/config_schema.html#template_name) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/assets/config_schema.md#template_name)
+- Different templates to choose from. More details: [HTML version](https://coveooss.github.io/json-schema-for-humans/docs/examples/examples_js_default/Configuration.html#template_name) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md#template_name)
 - Anchor links, allow to send a user to a specific section of the documentation
 - Support for references (even circular!)
 
@@ -22,7 +22,7 @@ pip install json-schema-for-humans
 
 ## Usage
 
-Options for generation of the doc are documented using the library itself: [HTML version](https://coveooss.github.io/json-schema-for-humans/assets/config_schema.html) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/assets/config_schema.md)
+Options for generation of the doc are documented using the library itself: [HTML version](https://coveooss.github.io/json-schema-for-humans/docs/examples/examples_js_default/Configuration.html) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md)
 
 They can be supplied in various ways:
 - Using a JSON or YAML configuration file with the CLI option `--config-file`
@@ -44,7 +44,7 @@ The default value for `RESULT_FILE` is `schema_doc.html`
 #### CLI options
 
 #### --config
-Supply generation config parameters. The parameters are documented in the JSON schema `config_schema.json` at the root of the repo or see the generated doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/assets/config_schema.html) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/assets/config_schema.md).
+Supply generation config parameters. The parameters are documented in the JSON schema `config_schema.json` at the root of the repo or see the generated doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/docs/examples/examples_js_default/Configuration.html) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md).
 
 Each parameter is in the format `--config parameter_name=parameter_value`. Example: `--config expand_buttons=true`. The parameter value must be valid JSON.
 
@@ -147,7 +147,7 @@ Templates control the style of the generated documentation.
 
 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/assets/config_schema.html#expand_buttons) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/assets/config_schema.md#expand_buttons))
+- 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/docs/examples/examples_js_default/Configuration.html#expand_buttons) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/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
@@ -173,10 +173,10 @@ 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/assets/config_schema.html#template_md_options_badge_as_image) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/assets/config_schema.md#template_md_options_badge_as_image)
+See doc: [HTML version](https://coveooss.github.io/json-schema-for-humans/docs/examples/examples_js_default/Configuration.html#template_md_options_badge_as_image) - [Markdown version](https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md#template_md_options_badge_as_image)
 
 Contributions are welcomed to improve it!
 
 
-# Contributing
-[See CONTRIBUTING.md](https://github.com/coveooss/json-schema-for-humans/blob/master/CONTRIBUTING.md)
+## Contributing
+[See CONTRIBUTING.md](CONTRIBUTING.md)
diff --git a/_sidebar.md b/_sidebar.md
@@ -1,6 +1,7 @@
+*Quickly generate HTML or Markdown documentation from a JSON schema*
+
 * [Home](/)
-* [Configuration js format](docs/examples/examples_flat_default/Configuration.html)
-* [Configuration markdown format](docs/examples/examples_md_default/Configuration.md)
+* [Configuration](docs/Configuration.md)
 * [Examples](docs/Examples.md)
-* [Contributing](CONTRIBUTING.md)
+* [Contributing](/CONTRIBUTING.md)
 * [LICENSE](/LICENSE.md)
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -0,0 +1,50 @@
+
+# Configuration <!-- {docsify-ignore-all} -->
+
+<!-- select:start -->
+<!-- select-menu-labels: Schema -->
+
+## --Configuration--
+### Configuration
+
+
+<details>
+<summary>Json schema - Click here to expand source code...</summary>
+
+[../config_schema.json](../config_schema.json ':include :type=code')
+</details>
+
+
+<details>
+<summary>Js template - Click here to expand the rendered result...</summary>
+<a href="/docs/examples/examples_js_default/Configuration.html" target="_blank">Open it in full page</a>
+
+[examples/examples_js_default/Configuration.html](examples/examples_js_default/Configuration.html ':include :type=iframe width=100% height=400px')
+</details>
+
+
+<details>
+<summary>Flat template - Click here to expand the rendered result...</summary>
+<a href="/docs/examples/examples_flat_default/Configuration.html" target="_blank">Open it in full page</a>
+
+[examples/examples_flat_default/Configuration.html](examples/examples_flat_default/Configuration.html ':include :type=iframe width=100% height=400px')
+</details>
+
+
+<details>
+<summary>Mardown without badge template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_default/Configuration.md](examples/examples_md_default/Configuration.md ':include')
+</details>
+
+
+<details>
+<summary>Mardown with badges template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_with_badges/Configuration.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_with_badges/Configuration.md](examples/examples_md_with_badges/Configuration.md ':include')
+</details>
+
+
+<!-- select:end -->