diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 00000000..c2cdfb8a
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,21 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+
+[*]
+
+# Change these settings to your own preference
+indent_style = space
+indent_size = 2
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.eslintrc.js b/.eslintrc.js
new file mode 100644
index 00000000..c6757a49
--- /dev/null
+++ b/.eslintrc.js
@@ -0,0 +1,24 @@
+module.exports = {
+ extends: [
+ 'eslint:recommended',
+ ],
+ plugins: [
+ 'prettier',
+ ],
+ env: {
+ es6: true,
+ browser: false,
+ node: true,
+ commonjs: true,
+ },
+ parserOptions: {
+ ecmaVersion: 7,
+ },
+ rules: {
+ 'prettier/prettier': ['error', {trailingComma: 'es5', singleQuote: true}],
+ 'no-console': 'off',
+ 'prefer-const': 'error',
+ 'eqeqeq': 'error',
+ 'no-useless-return': 'error',
+ }
+};
diff --git a/.gitignore b/.gitignore
index a72b52eb..309da4d9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,7 @@ results
npm-debug.log
node_modules
+
+.idea
+.DS_Store
+.vscode
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 00000000..f6cdf409
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+4.7.0
diff --git a/README.md b/README.md
index 1a5d4bbc..eb9086af 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,15 @@
-# RAML to HTML
+
+ 
+
-A simple RAML to HTML documentation generator, written for Node.js.
+
+ 
+
+
+A simple RAML to HTML documentation generator, written for Node.js, with theme support.
+
+### RAML version support
+raml2html 4 and higher only support RAML 1.0 files. Please stick with raml2html 3.x for RAML 0.8 support.
## Install
@@ -9,52 +18,105 @@ npm i -g raml2html
```
-## Usage
-As a command line script:
+## Themes
+raml2html ships with a default theme, but you can install more from NPM. For example, to render
+RAML to Markdown, you can install the raml2html-markdown-theme theme:
```
-raml2html example.raml > example.html
-raml2html -i example.raml -o example.html
+npm i -g raml2html-markdown-theme
```
-As a library:
+Search NPM for the "raml2html-theme" keyword (or use [this link](https://www.npmjs.com/browse/keyword/raml2html-theme))
+to find more themes.
+## Usage
+
+### As a command line script
+```
+raml2html --help
+raml2html example.raml > example.html
+raml2html --theme raml2html-markdown-theme example.raml > example.html
+raml2html --template my-custom-template.nunjucks -i example.raml -o example.html
```
-var raml2html = require('raml2html');
-// Using the default templates:
-// source can either be a filename, file contents (string) or parsed RAML object
-raml2html.parse(source, onSuccess, onError);
+### As a library
+
+#### Using the default theme, different themes, or your own Nunjucks templates
+```javascript
+const raml2html = require('raml2html');
+const configWithDefaultTheme = raml2html.getConfigForTheme();
+const configForDifferentTheme = raml2html.getConfigForTheme('raml2html-markdown-theme');
+const configWithCustomTemplate = raml2html.getConfigForTemplate('~/path/to/my-custom-template.nunjucks');
+
+// source can either be a filename, url, or parsed RAML object
+raml2html.render(source, configWithDefaultTheme).then(function(result) {
+ // Save the result to a file or do something else with the result
+}, function(error) {
+ // Output error
+});
+```
-// Using your own templates:
-// config should be an object with at least an `template` property
-raml2html.parseWithConfig(source, config, onSuccess, onError);
+#### Using your own processing function, for full control over the whole rendering process
+```javascript
+/**
+ * config should be an object with at least an `processRamlObj` property which is a function that receives the raw RAML
+ * object and must return a promise with the result. You can do whatever you want in this function.
+ *
+ * You can also supply a postProcessHtml function that can for example minify the generated HTML.
+ *
+ * You can also supply a writeOutput function that takes over writing the output (to disk for example).
+ *
+ * You can also supply a setupNunjucks function that takes the env as its only parameter.
+ */
+raml2html.render(source, config).then(function(result) {
+ // Save the result to a file or do something else with the result
+}, function(error) {
+ // Output error
+});
```
+See also [examples/script.js](https://github.com/raml2html/raml2html/blob/master/examples/script.js) for multiple examples of using raml2html as a library.
+
## Example output
-
+Please see the following links for live examples:
+- https://rawgit.com/raml2html/default-theme/master/examples/helloworld.html
+- https://rawgit.com/raml2html/default-theme/master/examples/world-music-api.html
+
+
+## Before you report a bug
+If you get parsing errors, please do not report them to raml2html: it doesn't do the actual RAML parsing.
+Review the error and fix your RAML file, or open a new issue at [raml-js-parser-2](https://github.com/raml-org/raml-js-parser-2).
-## Contribute
+## Contributing
raml2html is an open source project and your contribution is very much appreciated.
-1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
-2. Fork the repository on Github and make your changes on the develop branch (or branch off of it).
- Please retain the code style that is used in the project.
-3. Add an example of the new feature to example.raml (if applicable)
-4. Send a pull request (with the develop branch as the target).
+1. Fork the repository on Github and make your changes on the **develop** branch (or branch off of it).
+ Run `npm run lint` before committing to check for common problems and auto format all code.
+2. Add an example of the new feature to example.raml (if applicable)
+3. Send a pull request (with the **develop** branch as the target).
-A big thank you goes out to everyone who helped with the project, the [contributors](https://github.com/kevinrenskers/raml2html/graphs/contributors)
+If your pull request is merged feel free to ask for push access. We want to get more maintainers! If you do
+have push access, please still work on feature branches and create pull requests, which then get reviewed.
+You can also review other people's pull requests and be involved in that way.
+
+A big thank you goes out to everyone who helped with the project, the [contributors](https://github.com/raml2html/raml2html/graphs/contributors)
and everyone who took the time to report issues and give feedback.
+### Local setup
+To get the best environment to work on raml2html and the default theme, follow these steps.
+
+1. Checkout raml2html-default-theme's develop branch; `npm link`.
+2. Checkout raml2html's develop branch; first `npm link raml2html-default-theme` and then `npm link`.
+3. In raml2html-default-theme run `npm link raml2html`.
+
+Now both projects are installed globally, but using the local development versions of both.
+From the theme repo's examples folder you can run the `render-all-examples` script without problem.
-## To do
-This project is still very much a work in progress, but the output is quite usable already.
-* Template options (for example to turn off side bar navigation)
-* Finish HTML output, currently there's still some stuff missing (like securedBy and headers)
-* Different templates (for example render to Markdown to create awesome README's)
+## Changelog
+See [changelog.md](https://github.com/raml2html/raml2html/blob/master/changelog.md)
## License
diff --git a/bin/raml2html b/bin/raml2html
new file mode 100755
index 00000000..5bcc41d4
--- /dev/null
+++ b/bin/raml2html
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const yargs = require('yargs');
+const raml2html = require('..');
+const pjson = require('../package.json');
+
+const argv = yargs
+ .usage('Usage: raml2html [options] [RAML input file]')
+ .version(pjson.version)
+
+ .help('h')
+ .alias('h', 'help')
+
+ .string('i')
+ .alias('i', 'input')
+ .describe('i', 'Input file')
+
+ .string('o')
+ .alias('o', 'output')
+ .describe('o', 'Output file')
+
+ .string('t')
+ .alias('t', 'template')
+ .describe('t', 'Template path')
+
+ .boolean('p')
+ .alias('p', 'pretty')
+ .describe('p', 'Pretty output (non-minified)')
+
+ .boolean('v')
+ .alias('v', 'validate')
+ .describe('v', 'Validate RAML (off by default)')
+
+ .array('e')
+ .alias('e', 'extensionsAndOverlays')
+ .describe('e', 'Extensions and overlays paths')
+
+ .string('theme')
+ .describe('theme', 'Theme name')
+
+ .example('raml2html example.raml > example.html')
+ .example('raml2html --template my-template.nunjucks -i example.raml -o example.html')
+ .example('raml2html --theme raml2html-markdown-theme example.raml > example.html')
+ .example('raml2html -v example.raml > example.html')
+ .example('raml2html -e extension.raml overlay.raml -i example.raml -o example.html')
+ .argv;
+
+let input = argv.input;
+
+if (!input) {
+ if (argv._.length !== 1) {
+ console.error('Error: You need to specify the RAML input file\n');
+ yargs.showHelp();
+ process.exit(1);
+ }
+
+ input = argv._[0];
+}
+
+let config;
+if (argv.template) {
+ config = raml2html.getConfigForTemplate(argv.template);
+} else {
+ config = raml2html.getConfigForTheme(argv.theme, argv);
+}
+
+function writeOutput(result, config, argv) {
+ return new Promise((resolve, reject) => {
+ if (argv.output) {
+ fs.writeFile(argv.output, result, err => {
+ if (err) {
+ reject(err);
+ } else {
+ resolve();
+ }
+ });
+ } else {
+ // Simply output to console
+ process.stdout.write(result, resolve);
+ }
+ });
+}
+
+function errorPath(error) {
+ const dir = path.dirname(input);
+
+ return [
+ path.join(dir, error.path),
+ error.range.start.line,
+ error.range.start.column,
+ ].join(':');
+}
+
+function errorMessage(error) {
+ return `${error.code}: ${error.message}`;
+}
+
+function errorStackTrace(error, nocolor) {
+ let message = `${errorMessage(error)} (${errorPath(error)})`;
+
+ if (!nocolor) {
+ if (error.isWarning) {
+ message = chalk.yellow(message);
+ } else {
+ message = chalk.red(message);
+ }
+ }
+
+ if (error.trace) {
+ message += '\n ' + errorStackTrace(error.trace[0], true);
+ }
+
+ return message;
+}
+
+function writeParserErrors(parserErrors) {
+ parserErrors.forEach(error => {
+ console.error(errorStackTrace(error));
+ });
+}
+
+// Start the rendering process
+raml2html
+ .render(input, config, argv)
+ .then(result => {
+ return (config.writeOutput || writeOutput)(result, config, argv);
+ })
+ .then(() => process.exit(0))
+ .catch(error => {
+ if (error.message) {
+ console.error(chalk.bgRed(error.message) + '\n');
+ }
+
+ if (error.parserErrors) {
+ let parserErrors = error.parserErrors;
+
+ if (argv.suppressWarnings) {
+ parserErrors = parserErrors.filter(error => !error.isWarning);
+ }
+
+ if (argv.rawErrors) {
+ console.error(JSON.stringify(parserErrors, null, 2));
+ } else {
+ writeParserErrors(parserErrors);
+ }
+ }
+
+ process.exit(1);
+ });
diff --git a/changelog.md b/changelog.md
index 4835a690..ad27a8ca 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,3 +1,375 @@
+7.8.0 - Feb 21, 2021
+- Updated dependencies
+
+7.7.0 - Jan 25, 2021
+- Updated dependencies
+
+7.6.0 - Jul 16, 2020
+- Updated dependencies
+
+7.5.0 - Oct 30, 2019
+- Updated dependencies
+
+7.4.0 - May 29, 2019
+- Add support for RAML parser resolvers options
+
+7.3.0 - March 24, 2019
+- Updated 3rd party dependencies like marked and nunjucks
+
+7.2.2 - February 23, 2019
+- Removed unused CLI options and examples
+
+7.2.1 - November 27, 2018
+- Refix #259
+
+7.2.0 - September 11, 2018
+- You can now give paths to extensions and overlays using the `-e` option
+- Pretty printed parse errors by default when using the `--validate` option (turn off with `--raw-errors`)
+
+7.1.0 - April 6, 2018
+- Themes can now supply their own `writeOutput` function to control how they handle the output
+
+7.0.0 - February 18, 2018
+- Using raml2obj 6.0.0 and the new default theme 2.7.0
+
+6.7.0 - February 13, 2018
+- Added the `pretty` library as a dependency, for use with the `--pretty` option
+
+6.6.0 - January 20, 2018
+- CLI options are now added to ramlobj, so they can be used in templates
+
+6.5.0 - January 9, 2018
+- Switched marked dependency back to marked
+- Updated other dependencies like yargs, eslint, and prettier
+
+6.4.2 - November 10, 2017
+- Switched marked dependency to 8fold-marked
+
+6.4.1 - August 4, 2017
+- Fixed a bug where if no options were given at all to the render function you'd get an error
+
+6.4.0 - July 16, 2017
+- Added a new `--pretty` command line option to turn off html minification
+
+6.3.0 - April 25, 2017
+- Added a new `--validate` command line option to turn on validation, which is now off by default (#345)
+
+6.2.0 - April 21, 2017
+- Fixed template path handling (#343)
+
+6.1.1 - April 14, 2017
+- Updated third party dependencies
+
+6.1.0 - March 24, 2017
+- Updated raml2obj dependency, also made it less strict
+
+6.0.0 - March 17, 2017
+- Updated from raml2obj 4.1.0 to 5.1.0, which has backwards incompatible changes to securedBy
+ (among other bug fixes)
+- Updated to raml2html-default-theme 2.0.0 to deal with these securedBy changes
+
+5.1.0 - March 9, 2017
+- All program arguments can now be passed on to themes, so themes can support their own config options
+- Switched from using ESLint for code formatting to Prettier. We still use ESLint, Prettier is run as a plugin through it. ESLint still checks for bugs.
+
+5.0.0 - February 14, 2017
+- Added support for themes:
+ - the command line interface now takes an optional `--theme` parameter
+ - we ship two officially supported themes: raml2html-default-theme and raml2html-markdown-theme
+ - themes can overwrite the entire rendering process, allowing themes to use different templating engines
+ or output formats (Markdown, PDF, etc)
+ - the `getDefaultConfig` function has been split into `getConfigForTemplate` and `getConfigForTheme`,
+ use `getConfigForTheme` without any parameters to get the old behaviour of `getDefaultConfig`
+
+4.1.1 - February 6, 2017
+- Improved error reporting (#316)
+
+4.1.0 - January 28, 2017
+- Render more information about examples (name, description) (#313)
+- Render more security scheme data (#310)
+- Updated raml2obj, which
+ - Updated raml-js-parser-2 dependancy
+ - Fixed types' parent overriding behaviour
+
+4.0.6 - January 23, 2017
+- Fixed template render error (#305)
+
+4.0.5 - January 9, 2017
+- Fix array examples (#302)
+
+4.0.4 - December 27, 2016
+- Put properties before example for item (#299)
+- Fix template variable reference that prevented type properties from rendering (#300)
+
+4.0.3 - December 12, 2016
+- Render item examples (#293)
+
+4.0.2 - December 8, 2016
+- Improve error output (#289)
+
+4.0.1 - December 8, 2016
+- Documentation fixes
+
+4.0.0 - December 1, 2016
+- We're releasing 4.0.0 with RAML 1 support. Please keep in mind that we no longer support RAML 0.8 files. For other changes please check the beta's below.
+
+4.0.0-beta18 - November 30, 2016
+- Updated raml2obj
+
+4.0.0-beta17 - November 23, 2016
+- Improved rendering of nested properties (#274)
+
+4.0.0-beta16 - November 22, 2016
+- Improved rendering of inherited array properties (#277)
+
+4.0.0-beta15 - November 21, 2016
+- Updated raml2obj
+- Fixed rendering of type array of primitives (like string[])
+
+4.0.0-beta14 - November 3, 2016
+- Fixed template render error (#272)
+
+4.0.0-beta13 - November 2, 2016
+- Updated raml2obj to 4.0.0-beta13, fixing type expansion in uriParameters (#271)
+
+4.0.0-beta12 - November 1, 2016
+- Improved array type support (#265)
+
+4.0.0-beta11 - November 1, 2016
+- Updated raml2obj to 4.0.0-beta11, solving problems with JSON datatypes
+
+4.0.0-beta10 - October 31, 2016
+- Updated raml2obj to 4.0.0-beta10
+
+4.0.0-beta9 - October 19, 2016
+- Deal with object datatypes
+
+4.0.0-beta8 - October 14, 2016
+- Updated raml2obj to 4.0.0-beta9, which deals with type inheritance
+
+4.0.0-beta7 - October 5, 2016
+- Rendering types
+
+4.0.0-beta6 - October 4, 2016
+- Using raml2obj 4.0.0-beta7
+
+4.0.0-beta5 - September 30, 2016
+- Fixed files list in package.json
+
+4.0.0-beta4 - September 29, 2016
+- Using raml2obj 4.0.0-beta6 which expands types and always gives consistent examples arrays
+- Rendering baseUriParameters
+- Rendering `properties` instead of `formParameters`
+- Rendering multiple `examples`
+- Improved rendering of single item enums
+- Very basic initial rendering of annotations on methods
+- Removed rendering of `types` for now
+
+4.0.0-beta3 - September 27, 2016
+- Allow Nunjucks config via a `config.setupNunjucks` function (#261)
+- Fixed securedBy usage in the templates
+- Added a full featured RAML 1.0 example file (world-music-api.raml)
+- Fixed examples/script.js
+
+4.0.0-beta2 - September 26, 2016
+- Using raml2obj 4.0.0-beta3
+- Fixed templates to use the changed output from raml2obj
+- Added a new basic example RAML file
+- Removed a bunch of old examples
+
+3.0.1 - September 16, 2016
+- Fixed a problem where the output would be truncated after 65536 characters (#259)
+
+4.0.0-beta1 - August 10, 2016
+- Using raml2obj 4.0.0-beta1, which adds support for RAML 1.0
+ (even though raml2html's template doesn't support that yet)
+
+3.0.0 - August 10, 2016
+- Released without further changes
+
+3.0.0-beta2 - August 8, 2016
+- Updated to raml2obj 3.0.0-beta2
+- Fixed rendering of the github.raml example file (#249)
+
+3.0.0-beta1 - August 7, 2016
+- Updated code to use ES6 syntax
+- Updated all dependencies
+- Breaking change: Node 4 or higher is now required
+- Breaking change: nunjucks-markdown 2.0.0 is a bit fuzzy with whitespace, please check
+ https://github.com/raml2html/raml2html/pull/231 for help with updating your custom templates.
+
+2.5.0 - August 4, 2016
+- Updated highlight.js to 9.3.0
+- Added support for securedBy scopes
+- Added syntax highlighting within modals
+- Improved item display of values false and 0
+- Improved multiple security schemes handling
+- Horizontally scroll overflowing code snippets
+
+2.4.0 - March 12, 2016
+- Downgraded Nunjucks back to 1.3.0 due to peer conflicts with nunjucks-markdown
+ (which can't be upgraded because the newest version is broken)
+
+2.3.0 - February 23, 2016
+- Updated all 3rd party dependancies
+- Fix default tab selection
+- Improved security schema rendering
+- Expand $ref properties by using raml-json-expander
+
+2.2.0 - January 20, 2016
+- Now writing parse errors to STDERR
+
+2.1.2 - November 13, 2015
+- Better fix for #152 (#157)
+
+2.1.1 - November 5, 2015
+- Fix JS error in Chrome when opening the html file from the local file system and then closing a modal (#152)
+
+2.1.0 - August 25, 2015
+- Update third party dependencies and ESLint rules
+- Nunjucks 1.3.0 makes working with relative template includes a lot easier, use like this:
+ {% include "./resource.nunjucks" %}
+- Fixed bug where multiple instances of raml2html would share the Nunjucks config,
+ even if one of them needed to use a different templatePath
+- Removed the templatePath option from the CLI since relative templates now work as expected
+- Render description for securityScheme
+- Fixed table formatting
+
+2.0.2 - June 23, 2015
+- Fixed rendering of XML/HTML examples and schemes by properly escaping these variables (#140)
+
+2.0.1 - May 27, 2015
+- Fixed rendering of header
+
+2.0.0 - May 22, 2015
+- Using a promise based API, please see README for updated usage example
+- Using Nunjucks by default, instead of Handlebars
+- Made it a lot easier to completely customize the entire rendering process, allowing you for example to use not only
+ custom templates but even a different template engine
+- Got rid of the -s / https option, all external sources are simply always loaded via https
+- Got rid of the -r and -m template options, as the resource- and item templates are now simply loaded from within
+ the main template
+
+1.6.0 - March 24, 2015
+- Use hash tags for opening modals (#131)
+
+1.5.0 - March 11, 2015
+- Made the side menu a fixed height (#110)
+- Added a background color for PATCH (#117)
+- Response tab is set to active when request tab isn't shown (#120)
+- Added additional information in query parameter (#121)
+
+1.4.0 - January 30, 2015
+- If an example's type is explicitly set to 'string' then don't syntax highlight it
+
+1.3.1 - January 28, 2015
+- Fixed the id's of the tabs (#108)
+
+1.3.0 - January 21, 2015
+- Now rendering default values for parameters (#100) and securedBy (#10)
+
+1.2.0 - January 20, 2015
+- Greatly simplified the loading of (custom) templates and the default behaviour of `getDefaultConfig`.
+ Sadly loading remote template files is no longer possible from the command line, but you can always create a simple
+ wrapper script if you need this functionality. Please let me know if this is a feature you absolutely need.
+
+1.1.1 - January 20, 2015
+- Fixed default behaviour of calling `getDefaultConfig` with no arguments,
+ which should always use the default templates
+
+1.1.0 - January 14, 2015
+- Now using raml-parser's FileReader which makes it a lot easier to load custom templates
+ in other folders or even as remote urls (#96)
+
+1.0.6 - January 14, 2015
+- Bugfix: use passed in template parameter when checking paths (#98)
+
+1.0.5 - December 3, 2014
+- Configured the html minifier to keep the quotes around html attributes (#93)
+
+1.0.4 - September 25, 2014
+- Updated readme and raml2obj version
+
+1.0.3 - September 12, 2014
+- Fixed method :hover effect, which was broken after #63
+
+1.0.2 - September 12, 2014
+- Improved detection of empty resources
+
+1.0.1 - September 10, 2014
+- Solved problem with indentation of code examples (#66)
+- Added `--version` command line option (#75)
+
+1.0.0 - September 10, 2014
+- **Finalized API, replaced `parse`/`parseWithConfig` with a single `render` method**
+- Added a way for users to specify their own output processing via a `processOutput` function in the config object
+
+0.32.0 - September 9, 2014
+- Support for custom templates via command line parameters (#72)
+
+0.31.2 - September 6, 2014
+- Support enums for headers and URI parameters (#59)
+- Rendering URI parameter examples (#57)
+- Greatly simplified `resource.handlebars` by moving all the common code into a separate partial
+
+0.31.1 - August 21, 2014
+- Fixed HTML validity (#61)
+- Fixed rendering of links within Markdown content (#63)
+
+0.31.0 - August 21, 2014
+- Improved rendering of tables within Markdown content
+
+0.30.0 - July 16, 2014
+- Adding `-s` command line parameter to use https links in the generated html file (it uses http by default)
+- Deprecated the `parse` function, use `parseWithConfig` instead (in combination with the `getDefaultConfig` function)
+- Bugfix: fixed html escaping for XML/HTML content (#53)
+
+0.29.0 - July 16, 2014
+- Moved code highlighting to the client to generate smaller HTML output
+- Use a HTML minifier to generate MUCH smaller output
+- Don't html-escape string in `` blocks
+- The GitHub example used to be 3.2 MB, after these changes it's down to 1.2 MB
+
+0.28.0 - July 14, 2014
+- Render descriptions for nested resources
+- Made the method badges clickable directly from the collapsed panel
+
+0.27.0 - July 10, 2014
+- Added a new public function `getDefaultConfig`
+
+0.26.0 - July 10, 2014
+- Render required and description of URI Parameters
+- Made the output of URI params, form params, request body and response body consistent with each other
+
+0.25.0 - July 9, 2014
+- Added code highlighting to the Markdown parser
+
+0.24.0 - July 7, 2014
+- Added header examples
+
+0.23.2 - July 7, 2014
+- Fixed escape key not closing the modal
+
+0.23.1 - June 29, 2014
+- Fixed Markdown output for long sentences
+- Added GitHub API example
+
+0.23.0 - June 29, 2014
+- Parse method descriptions in the main view with Markdown as well
+
+0.22.1 - June 21, 2014
+- Fixed error handling
+
+0.22.0 - June 21, 2014
+- Added headers to request and response information
+
+0.21.0 - June 12, 2014
+- Split all the raml parsing logic into its own [raml2obj project](https://github.com/kevinrenskers/raml2obj)
+
+0.20.0 - June 4, 2014
+- Fixed html output
+- Added anchors to top level documentation chapters
+
0.19.0 - May 28, 2014
- External resources automatically switch between http and https links
- Attach the config object to the RAML object so it's accessible in your handlebars templates
@@ -20,7 +392,7 @@
0.15.0 - May 12, 2014
- Show padlock for secured methods (#14)
-- Bugfix: Handle resource urls with periods (#15)
+- Bugfix: handle resource urls with periods (#15)
0.14.0 - May 6, 2014
- Better schema handling (#12)
@@ -35,16 +407,16 @@
- Render the description of query params with Markdown
0.10.0 - April 8, 2014
-- New parseWithConfig method allowing you to override the templates (#5)
+- New `parseWithConfig` method allowing you to override the templates (#5)
0.9.0 - April 8, 2014
-- Allow raml2html to be used pragmatically from another module
+- Allow raml2html to be used from another module
0.8.2 - April 7, 2014
- Showing all uri parameters, also those from parents
0.8.1 - April 7, 2014
-- Code cleanup, added allUriParameters property to every resource
+- Code cleanup, added `allUriParameters` property to every resource
0.8.0 - April 5, 2014
- Improved rendering of query params: show required, enum and example
diff --git a/example.html b/example.html
deleted file mode 100644
index b28fce6c..00000000
--- a/example.html
+++ /dev/null
@@ -1,2393 +0,0 @@
-
-
-
- Codestin Search App
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
ACCOUNTS
-
-
-
-
-
-
This is the top level description for /account.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Creates a new account. Some bold text here.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "email": "john@example.com",
- "password": "super_secret",
- "name": "John Doe"
-}
-
-
-
-
-
-
-
-
-
-
HTTP status code 200
-
Account was created and user is now logged in
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Query Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
Body
-
-
Type: application/x-www-form-urlencoded
-
-
Form Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Login with email and password
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "email": "john@example.com",
- "password": "super_secret"
-}
-
-
-
-
-
-
-
-
-
-
HTTP status code 200
-
Login was correct
-
-
-
-
-
-
-
HTTP status code 400
-
Login was incorrect, please try again
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Sends an email to the user with a link to set a new password
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "email": "john@example.com"
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Deletes the session, logging out the user
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
/conversations
-
-
-
-
-
-
This is the top level description for /conversations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get a list of conversation for the current user
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Create a new conversions. The currently logged in user doesn't need to be supplied in the members list, it's implied.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "content": "My message!",
- "members": [1, 2, 3]
-}
-
-
-
-
-
-
-
-
-
-
HTTP status code 200
-
A conversation with these members already existed, the message was added to that one
-
-
-
-
-
-
-
HTTP status code 201
-
The conversation was created and the message added to it
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get a single conversation including its messages
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Update a conversation (change members)
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get the messages for the conversation
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
Query Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Add a new message to a conversation
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
- - convId: string
-
- - messageId: string
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
- - convId: string
-
- - messageId: string
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
/users
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get a list of all users
-
-
-
-
-
-
-
-
-
-
-
-
Query Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "email": "john@example.com",
- "name": "John Doe",
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get the details of a user including a list of groups he belongs to
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
/groups
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get a list of all the groups
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "name": "Cool people",
- "members": [1, 2, 3]
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Get the details of a group, including the member list
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Update the group, optionally supplying the new list of members (overwrites current list)
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "name": "Cool people",
- "members": [1, 2, 3]
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
-
-
-
-
-
Body
-
-
Type: application/json
-
-
-
-
Example:
-
{
- "user_id": 4,
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Removes a user from a group
-
-
-
-
-
-
-
-
-
-
URI Parameters
-
-
- - groupId: string
-
- - userId: string
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\n\n\nHi!
');
+ });
+ },
+
+ postProcessHtml: config1.postProcessHtml,
+};
+
+raml2html.render(ramlFile, config3).then(
+ result => {
+ console.log('3: ', result.length);
+ },
+ error => {
+ console.log('error! ', error);
+ }
+);
+
+/**
+ * You can also customize the postProcessHtml function.
+ */
+const config4 = {
+ processRamlObj() {
+ return new Promise(resolve => {
+ resolve('Hi!
');
+ });
+ },
+
+ postProcessHtml() {
+ return new Promise(resolve => {
+ resolve('ABC');
+ });
+ },
+};
+
+raml2html.render(ramlFile, config4).then(
+ result => {
+ console.log('4: ', result.length);
+ },
+ error => {
+ console.log('error! ', error);
+ }
+);
+
+/**
+ * Testing if it works with no config at all. It outputs a JSON version of the RAML file.
+ */
+raml2html.render(ramlFile, {}).then(
+ result => {
+ console.log('5: ', Object.keys(result).length);
+ },
+ error => {
+ console.log('error! ', error);
+ }
+);
+
+/**
+ * If you want to only customize the Nunjucks configuration, just add a setupNunjucks function to the default config.
+ */
+const config6 = raml2html.getConfigForTheme('raml2html-default-theme');
+config6.setupNunjucks = function(env) {
+ // Do stuff with env here
+ env.bla = 'bla';
+};
+
+raml2html.render(ramlFile, config6).then(
+ result => {
+ console.log('6: ', result.length);
+ },
+ error => {
+ console.log('error! ', error);
+ }
+);
diff --git a/index.js b/index.js
new file mode 100644
index 00000000..c400b812
--- /dev/null
+++ b/index.js
@@ -0,0 +1,171 @@
+'use strict';
+
+const raml2obj = require('raml2obj');
+const pjson = require('./package.json');
+const nunjucks = require('nunjucks');
+const markdown = require('nunjucks-markdown');
+const marked = require('marked');
+const Minimize = require('minimize');
+const pretty = require('pretty');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Render the source RAML object using the config's processOutput function
+ *
+ * The config object should contain at least the following property:
+ * processRamlObj: function that takes the raw RAML object and returns a promise with the rendered HTML
+ *
+ * @param {(String|Object)} source - The source RAML file. Can be a filename, url, or an already-parsed RAML object.
+ * @param {Object} config
+ * @param {Object} options
+ * @param {Function} config.processRamlObj
+ * @returns a promise
+ */
+function render(source, config, options) {
+ config = config || {};
+ config.raml2HtmlVersion = pjson.version;
+
+ // Check if option is old boolean `validation` to keep backward compatibility
+ if (typeof options === 'boolean') {
+ options = {
+ validate: options,
+ };
+ }
+
+ if (options === undefined) {
+ options = {
+ validate: false,
+ };
+ }
+
+ return raml2obj
+ .parse(source, {
+ validate: options.validate,
+ extensionsAndOverlays: options.extensionsAndOverlays,
+ httpResolver: options.httpResolver,
+ fsResolver: options.fsResolver,
+ })
+ .then(ramlObj => {
+ if (config.processRamlObj) {
+ return config.processRamlObj(ramlObj, config, options).then(html => {
+ if (config.postProcessHtml) {
+ return config.postProcessHtml(html, config, options);
+ }
+ return html;
+ });
+ }
+
+ return ramlObj;
+ });
+}
+
+/**
+ * @param {String} [mainTemplate] - The filename of the main template, leave empty to use default templates
+ * @returns {{processRamlObj: Function, postProcessHtml: Function}}
+ */
+function getConfigForTemplate(mainTemplate) {
+ const templatesPath = path.dirname(fs.realpathSync(mainTemplate));
+ const templateFile = path.basename(fs.realpathSync(mainTemplate));
+
+ return {
+ processRamlObj(ramlObj, config, options) {
+ // Extend ramlObj with config and options so the templates can use those values
+ ramlObj.config = config;
+ ramlObj.options = options;
+
+ const renderer = new marked.Renderer();
+ renderer.table = function(thead, tbody) {
+ // Render Bootstrap style tables
+ return ``;
+ };
+
+ // Setup the Nunjucks environment with the markdown parser
+ const env = nunjucks.configure(templatesPath, { autoescape: false });
+
+ if (config.setupNunjucks) {
+ config.setupNunjucks(env);
+ }
+
+ markdown.register(env, md => marked(md, { renderer }));
+
+ ramlObj.isStandardType = function(type) {
+ if (typeof type === 'object') {
+ return false;
+ }
+ return type && type.indexOf('{') === -1 && type.indexOf('<') === -1;
+ };
+
+ // Render the main template using the raml object and fix the double quotes
+ let html = env.render(templateFile, ramlObj);
+ html = html.replace(/"/g, '"');
+
+ // Return the promise with the html
+ return new Promise(resolve => {
+ resolve(html);
+ });
+ },
+
+ postProcessHtml(html, config, options) {
+ if (options.pretty) {
+ return pretty(html, { ocd: true });
+ } else {
+ // Minimize the generated html and return the promise with the result
+ const minimize = new Minimize({ quotes: true });
+
+ return new Promise((resolve, reject) => {
+ minimize.parse(html, (error, result) => {
+ if (error) {
+ reject(new Error(error));
+ } else {
+ resolve(result);
+ }
+ });
+ });
+ }
+ },
+ };
+}
+
+/**
+ * @param {String} [theme] - The name of a raml2html template, leave empty if you want to use the mainTemplate option
+ * @param {Object} [programArguments] - An object containing all program aruments
+ * @returns {{processRamlObj: Function, postProcessHtml: Function}}
+ */
+function getConfigForTheme(theme, programArguments) {
+ if (!theme) {
+ theme = 'raml2html-default-theme';
+ }
+
+ try {
+ // See if the theme supplies its own config object (or function that creates this object), and return it
+ const config = require(theme);
+
+ // If it's a function then call it with the program arguments
+ if (typeof config === 'function') {
+ return config(programArguments);
+ }
+
+ // Otherwise we assume it's a config object (default behavior)
+ return config;
+ } catch (err) {
+ // Nope, forward to getConfigForTemplate
+ const templatesPath = path.dirname(
+ require.resolve(`${theme}/package.json`)
+ );
+ return getConfigForTemplate(path.join(templatesPath, 'index.nunjucks'));
+ }
+}
+
+module.exports = {
+ getConfigForTemplate,
+ getConfigForTheme,
+ render,
+};
+
+if (require.main === module) {
+ console.error(
+ "This script is meant to be used as a library. You probably want to run bin/raml2html if you're looking for a CLI."
+ );
+ process.exit(1);
+}
diff --git a/lib/raml2html.js b/lib/raml2html.js
deleted file mode 100755
index 19c939a2..00000000
--- a/lib/raml2html.js
+++ /dev/null
@@ -1,192 +0,0 @@
-#!/usr/bin/env node
-
-'use strict';
-
-var raml = require('raml-parser');
-var handlebars = require('handlebars');
-var hljs = require('highlight.js');
-var marked = require('marked');
-var program = require('commander');
-var fs = require('fs');
-
-function parseBaseUri(ramlObj) {
- // I have no clue what kind of variables the RAML spec allows in the baseUri.
- // For now keep it super super simple.
- if (ramlObj.baseUri){
- ramlObj.baseUri = ramlObj.baseUri.replace('{version}', ramlObj.version);
- }
- return ramlObj;
-}
-
-function makeUniqueId(resource) {
- var fullUrl = resource.parentUrl + resource.relativeUri;
- return fullUrl.replace(/\W/g, '_');
-}
-
-function traverse(ramlObj, parentUrl, allUriParameters) {
- var resource, index;
- for (index in ramlObj.resources) {
- if (ramlObj.resources.hasOwnProperty(index)) {
- resource = ramlObj.resources[index];
- resource.parentUrl = parentUrl || '';
- resource.uniqueId = makeUniqueId(resource);
- resource.allUriParameters = [];
-
- if (allUriParameters) {
- resource.allUriParameters.push.apply(resource.allUriParameters, allUriParameters);
- }
-
- if (resource.uriParameters) {
- var key;
- for (key in resource.uriParameters) {
- resource.allUriParameters.push(resource.uriParameters[key]);
- }
- }
-
- traverse(resource, resource.parentUrl + resource.relativeUri, resource.allUriParameters);
- }
- }
-
- return ramlObj;
-}
-
-function markDownHelper(text) {
- if (text && text.length) {
- return new handlebars.SafeString(marked(text));
- } else {
- return '';
- }
-}
-
-function highlightHelper(text) {
- if (text && text.length) {
- return new handlebars.SafeString(hljs.highlightAuto(text).value);
- } else {
- return '';
- }
-}
-
-function lockIconHelper(securedBy) {
- if (securedBy && securedBy.length) {
- var index = securedBy.indexOf(null);
- if (index !== -1) {
- securedBy.splice(index, 1);
- }
-
- if (securedBy.length) {
- return new handlebars.SafeString(' ');
- }
- }
-
- return '';
-}
-
-function compileRamlObj(ramlObj, config, onSuccess) {
- ramlObj = parseBaseUri(ramlObj);
- ramlObj = traverse(ramlObj);
- ramlObj.config = config;
-
- // Register handlebar helpers
- for (var helperName in config.helpers) {
- if (config.helpers.hasOwnProperty(helperName)) {
- handlebars.registerHelper(helperName, config.helpers[helperName]);
- }
- }
-
- // Register handlebar partials
- for (var partialName in config.partials) {
- if (config.partials.hasOwnProperty(partialName)) {
- handlebars.registerPartial(partialName, config.partials[partialName]);
- }
- }
-
- var result = config.template(ramlObj);
- onSuccess(result);
-}
-
-function sourceToRamlObj(source, onSuccess, onError) {
- if (typeof(source) === 'string') {
- if (fs.existsSync(source)) {
- // Parse as file
- raml.loadFile(source).then(onSuccess, onError);
- } else {
- // Parse as string or buffer
- raml.load('' + source).then(onSuccess, onError);
- }
- } else if (source instanceof Buffer) {
- // Parse as buffer
- raml.load('' + source).then(onSuccess, onError);
- } else if (typeof(source) === 'object') {
- // Parse RAML object directly
- process.nextTick(function() {
- onSuccess(source);
- });
- } else {
- onError(new Error('sourceToRamlObj: You must supply either file, data or obj as source.'));
- }
-}
-
-function parseWithConfig(source, config, onSuccess, onError) {
- sourceToRamlObj(source, function(ramlObj) {
- compileRamlObj(ramlObj, config, onSuccess);
- }, onError);
-}
-
-function parse(source, onSuccess, onError) {
- var template = require('./template.handlebars');
- var resourceTemplate = require('./resource.handlebars');
-
- var config = {
- 'template': template,
- 'helpers': {
- 'md': markDownHelper,
- 'highlight': highlightHelper,
- 'lock': lockIconHelper
- },
- 'partials': {
- 'resource': resourceTemplate
- }
- };
-
- parseWithConfig(source, config, onSuccess, onError);
-}
-
-
-if (require.main === module) {
- program
- .usage('[options] [RAML input file]')
- .option('-i, --input [input]', 'RAML input file')
- .option('-o, --output [output]', 'HTML output file')
- //.option('-t, --template [template]', 'Template file to use') // for the future :)
- .parse(process.argv);
-
- var input = program.input;
-
- if (!input) {
- if (program.args.length !== 1) {
- console.error('Error: You need to specify the RAML input file');
- program.help();
- process.exit(1);
- }
-
- input = program.args[0];
- }
-
- // Start the parsing process
- parse(input, function(result) {
- if (program.output) {
- fs.writeFileSync(program.output, result);
- } else {
- // Simply output to console
- process.stdout.write(result);
- process.exit(0);
- }
- }, function(error) {
- console.log('Error parsing: ' + error);
- process.exit(1);
- });
-}
-
-
-module.exports.parse = parse;
-module.exports.parseWithConfig = parseWithConfig;
diff --git a/lib/resource.handlebars b/lib/resource.handlebars
deleted file mode 100644
index 72e3b602..00000000
--- a/lib/resource.handlebars
+++ /dev/null
@@ -1,198 +0,0 @@
-
-
-
-
- {{#methods}}
-
-
-
-
-
-
{{md description}}
-
-
-
-
-
-
-
- {{#if ../allUriParameters}}
-
URI Parameters
-
- {{#each ../../allUriParameters}}
- - {{this.displayName}}: {{this.type}}
- {{/each}}
-
- {{/if}}
-
- {{#if queryParameters}}
-
Query Parameters
-
- {{/if}}
-
- {{#if body}}
-
Body
- {{#each body}}
-
Type: {{@key}}
- {{#if formParameters}}
-
Form Parameters
-
- {{/if}}
- {{#if this.schema}}
-
Schema:
-
{{highlight this.schema}}
- {{/if}}
- {{#if this.example}}
-
Example:
-
{{highlight this.example}}
- {{/if}}
- {{/each}}
- {{/if}}
-
-
- {{#if responses}}
-
- {{#each responses}}
-
HTTP status code {{@key}}
- {{md this.description}}
-
- {{#if this.headers}}
-
Headers
-
- {{#each this.headers}}
- - {{@key}}: {{this.type}}
- {{/each}}
-
- {{/if}}
-
- {{#if this.body}}
-
Body
- {{#each this.body}}
-
Type: {{@key}}
- {{#if this.schema}}
-
Schema:
-
{{highlight this.schema}}
- {{/if}}
- {{#if this.example}}
-
Example:
-
{{highlight this.example}}
- {{/if}}
- {{/each}}
- {{/if}}
- {{/each}}
-
- {{/if}}
-
-
-
-
-
- {{/methods}}
-
-
-
-
-
- {{#resources}}
-
-
-
{{#if displayName}}{{displayName}}{{/if}}{{#unless displayName}}{{relativeUri}}{{/unless}}
-
-
-
- {{#if description}}
-
- {{md description}}
-
- {{/if}}
-
-
- {{> resource}}
-
-
-
- {{/resources}}
-
-
-
-
-
-
-