Skip to content
Browse files

Merge pull request #2 from nickl-/master

README v2.0
  • Loading branch information...
2 parents 12f151f + 2c754ff commit da22821963a7b49d2fb4aaa89e19034fb115f84a @mattyod committed Dec 20, 2012
Showing with 62 additions and 45 deletions.
  1. +62 −45 README.md
View
107 README.md
@@ -1,91 +1,108 @@
# Matic [![Build Status](https://secure.travis-ci.org/mattyod/matic.png?branch=master)](http://travis-ci.org/mattyod/matic)
A Node.js build tool for generating HTML documentation from JSON schemas.
-Matic is currently in an Alpha state of development and whilst usable is quite far from being a complete and production ready tool.
+Matic is currently in Alpha state and whilst usable for most use cases still lots of work remain as development continues. You are encouraged to fork the repo should you wish to contribute to the code and bug reports or suggestions will be attended to in the issue queue.
-Current development has been based on [draft JSON schema 03](http://tools.ietf.org/html/draft-zyp-json-schema-03) but as specification for draft 04 emerge in more detail the aim is to adapt as quickly as possible to any changes that may bring.
+Current development was based on the [draft JSON schema 03](http://tools.ietf.org/html/draft-zyp-json-schema-03) specification and support for any follow up specifications will be ported as they become available.
## Installation
-Use NPM to install globally with:
+Use NPM to install globally:
- npm install -g
+ $ npm install -g
-To confirm installation you should now be able to run the command:
+A sure indication that matic is installed and operational, which also retrieves the current version number, is to run the command:
- matic -v
-
-Which should output the currently installed version of Matic.
+ $ matic -v
## Building documentation
-From the root of your project simply type:
+From the root of your project folder simply run:
- matic
+ $ matic
-For an examples of how to structure your project folder there are currently two examples available both of which are full project folder that have not yet been built with Matic:
+### Example projects
+There are currently two example projects available, which are full project folders not yet built with Matic, to aid as examples of how to structure your project folder to work with Matic:
* [very simple example](https://github.com/mattyod/matic-very-simple-example). Which contains one schema file and one template file.
- * [simple example](https://github.com/mattyod/matic-simple-example). Which contains one schema file and a more structured template set up with includes and mixins.
+ * [simple example](https://github.com/mattyod/matic-simple-example). Which contains one schema file and a more structured template set-up with includes and mixins.
+
+A more complex example which includes sub schema support is currently underway and will be available shortly.
-A more complex example that includes sub schemas will follow shortly.
+A typical layout using default settings:
-Essentially you will need a folder with at least one schema in it and another folder with at least one template file in it. Currently Matic has only been tested with Jade templates but in theory should work with any templating language that uses the methods compile() and render().
+```
+|____config.json
+|____schemas
+| |____my-awesome-schema.json
+|____templates
+| |____default.jade
+|____web
+```
-Initially Matic's config is set to look for a main template with the filename default.jade but this can be over-ridden with a project level config file, see below.
+Essentially you will need
+ * a folder with at least one schema document
+ * a folder with at least one template file
+ * an optional config file for custom settings
-By default Matic will then use your template(s) and schema(s) to output a set of HTML files into a new folder called 'web', again this can be over-ridden with a local config file.
+The default global configuration looks for a main template with filename `default.jade` which can be customized with a project level config file, [see below](#setting-config-options).
+
+By default Matic will use your template(s) and schema(s) to generate a set of HTML files into a folder named `web`, this can also be modified through the local config file.
## Setting config options
-Various default paths and parameters are set by default within Matic's internal config file. Any of these parameters can be over-ridden on a project by project basis by creating your own config.json object file at the project root.
+Various default settings are configured through Matic's global config file. These settings can be modified on a per project basis by providing a custom `config.json` file located at the root of the project folder.
-The default config contains the following parameters:
+The following parameters are configurable, default values in brackets:
-### Source
-This is the source folder that Matic will look in for JSON schema files. These files can have any name but must be of type .json.
+### Source [./schemas/]
+The source folder is where Matic will look for JSON schema documents. These files can have any name with the `.json` extension.
Example:
+```json
+{"source": "./schemas/"}
+```
- {"source": "./schemas/"}
-
-### Target
-This is the target folder that Matic will place generated HTML files into. The named folder does not need to exist when you run Matic as a new one will be created if an existing one cannot be found.
+### Target [./web/]
+This is the output folder where Matic will generate the resulting HTML files. This folder will be created automatically, if it does not exist.
Example:
-
- {"target": "./web/"}
+```json
+{"target": "./web/"}
+```
### Template
-This is an object containing details of the templating language that you intend Matic to use to generate your HTML output with. Please note at this time no testing has been carried out with any other language than Jade. It should work for others in theory but until I test that, you have been warned.
+This is an object containing details of the templating language which you intend Matic to use to generate the HTML output. Please note only support for Jade has been tested to date, although it should work equally well with other libraries which implement the `compile()` and `render()` methods. If you do happen to have the opportunity to test Matic with an alternative provider, please report back with your findings.
-Parameters within the template object are:
+The template configuration object has the following settings:
-#### Path
+#### Path [./templates/]
The path to your template files.
-#### File
+#### File [default]
The name of your primary template file.
-#### Lib
-The template library that you are using. N.B. Matic will assume that this is the file suffix of your template files.
+#### Lib [jade]
+Name of the template library to use. **Note:** Matic will assume that the template files have the same extension. i.e. default.jade
Example:
+```json
+"template": {
+ "path": "./templates/",
+ "file": "default",
+ "lib": "jade"
+}
+```
- "template": {
- "path": "./templates/",
- "file": "default",
- "lib": "jade"
- }
-
-For this example Matic will expect to find a folder at the project root called 'templates', which contains a template file named default.jade.
+In this example Matic will expect to find a file named default.jade located in the templates folder at the root of your project.
-### Assets
-An array of files or folders that you want copied into your target folder. There is no assets reference by default within Matic, you will need to add your own config.json file to the project root if you want Matic to copy over any additional assets. Original assets will be left un-touched.
+### Assets [ ]
+An array of files or folders to be copied into the target build folder. There are no resources referenced by default, you will need to add your own config.json file to the project root if you want Matic to copy additional files and/or folders during build. The original resources will remain unchanged.
Example:
+```json
+{"assets": ["css", "js"]}
+```
- {"assets": ['css', 'js']}
-
-The above example would inform Matic that two folders 'css' and 'js', need to be copied into the target build folder. Copying is recursive so all sub folders and files within those folders will be copied across as well.
+This example instructs Matic to copy two folders named `css` and `js` into the target build folder. Copying is done recursively which includes all files and sub folders.
## Licence
-[MIT](https://github.com/mattyod/matics/blob/master/LICENSE)
+[MIT](https://raw.github.com/mattyod/matic/master/LICENSE)

0 comments on commit da22821

Please sign in to comment.
Something went wrong with that request. Please try again.