Dox-ray

Dox-ray is a node module that can parse special code comments and return
an array of objects containing document/code pairs. Comments are written in YAML
and parsed into structured objects. The YAML structure is up to you. You define
the documentation properties that's right for your code. Dox-ray can also
write to a JS or JSON file which you can use to build completely client-side
documentation sites that won't slow down your task runner.

Note that this project is currently in Beta.

Getting started

$3

``bash
$ npm install dox-ray
`

$3

#### First, you'll need a file to parse

Here's how you write a Dox-ray comment:

_styles.less:_

`css
/* doxray
label: Button
markup: Button
notes:
- >
Don't use anchor elements as buttons unless they actually link to
another page."
*/
.btn {
font-size: unit(14px / 16px, em);
}
`

#### Now set up Dox-ray to parse stuff

`js
var doxray = require('dox-ray');
var docs = doxray(['styles.less']);
`

_In the above example, docs is equal to the following:_

`js
[
{
"label": "Button",
"markup": "Button,"
"notes": [ "Don't use anchor elements as buttons unless they actually link to another page." ],
"filename": "styles.less",
"less": ".btn {\nfont-size: unit(14px / 16px, em);\n}"
}
]
`

##### You can also save it to a JS or JSON file

`js
var docs = doxray(['styles.less'], {
jsFile: 'styles.js',
jsonFile: 'styles.json'
});
`

_styles.js:_

`js
Doxray = {
"patterns": [
{
"label": "Button",
"markup": "Button,"
"notes": [ "Don't use anchor elements as buttons unless they actually link to another page." ],
"filename": "styles.less",
"less": ".btn {\nfont-size: unit(14px / 16px, em);\n}"
}
],
"getByProperty": function ( property, value ) {
return this.patterns.filter(
this.utils.hasProperty( property, value )
);
},
"utils": {
"hasProperty": function ( property, value ) {
return function( pattern ) {
if ( typeof value === 'undefined' ) {
return pattern[ property ];
} else {
return pattern[ property ] && pattern[ property ].toLowerCase() === value.toLowerCase();
}
}
}
}
}
`

_styles.json:_

`json
[
{
"label": "Button",
"markup": "Button,"
"notes": [ "Don't use anchor elements as buttons unless they actually link to another page." ],
"filename": "styles.less",
"less": ".btn {\nfont-size: unit(14px / 16px, em);\n}"
}
]
`

$3

In order to make the regex simple, Dox-ray comments must start with an opening
comment, a space, then the word "doxray". The closing comment must be on a new
line.

`html

`

#### Supported comments

| Style | Example |
| ----- | ------- |
| CSS/JS | / / |
| HTML | |

You can easily add more by extending Doxray.prototype.regex.
See https://github.com/himedlooff/dox-ray/blob/master/doxray.js#L144-L155

#### YAML structure

You can structure the YAML within the Dox-ray comments however you want but
there are a few top level property names that are reserved. They are:

- filename
- (any file type you want to parse, for example css, less, md, js, html, etc)

The built-in Dox-ray processors will also add the following extra top level
properties:

- colorPalette
- label

You can disable these properties from getting generated by disabling the
processors before running Dox-ray. For example

`js
var doxray = require('dox-ray');
var docs = doxray(['styles.less'], { processors: [] });
`

$3

Once Dox-ray parses the data it can run processing functions to manipulate the
data. Dox-ray runs two processors out of the box.

#### Slugify

If you use the label property in your Dox-ray comment the Slugify processor
will use that value to create a slug property. Slugs are useful for creating
HTML id's so you can link to specific sections of a page.

For example, this comment:

`css
/* doxray
label: Primary Button
*/
`

Will automatically parse to this:

`js
{
label: "Primary Button",
slug: "primary-button"
}
`

#### Color Palette

Dox-ray will generate color palette data automatically if you specify a
colorPalette property in your Dox-ray comment. All you need to do is set the
value of the colorPalette property to the file type that contains
variable/color pairs. _Note that this only works when using a preprocessor like
SASS or Less._

For example, this comment:

`scss
/* doxray
colorPalette: less
*/
@white: #fff;
@black: #000;
`

Will automatically parse to this:

`js
{
colorPalette: [
{ variable: "@white", value: "#fff" },
{ variable: "@black", value: "#000" }
]
}
`

Getting involved

Feedback and contributions are welcome.
Please read CONTRIBUTING.

When submitting a pull request that changes or adds functionality please update
the tests and run:

`bash
$ npm test
``

To file a bug please us this handy template.

----

Open source licensing info

This projected is licensed under the terms of the MIT license.

----

Credits and references

This project was inspired by topdoc.
:smile: