Parse documentation from code comments
npm install doxray_This project has changed from "dox-ray" to "doxray"._
_There's no need to ever use the dash._
Doxray 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. Doxray 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.
You can find a Doxray template at
Note that this project is currently in Beta.
``bash`
$ npm install doxray
#### First, you'll need a file to parse
Here's how you write a Doxray comment:
_styles.less:_
`css`
/* doxray
label: Button
markup:
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 Doxray to parse stuff
`js`
var doxray = require('doxray');
var docs = doxray(['styles.less']);
_In the above example, docs is equal to the following:_
`js`
[
{
"label": "Button",
"markup": "",
"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 using the second argument to pass options
`js`
var docs = doxray(['styles.less'], {
jsFile: 'styles.js',
jsonFile: 'styles.json'
});
_styles.js:_
`js`
Doxray = {
"patterns": [
{
"label": "Button",
"markup": "",
"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": "",
"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}"
}
]
In order to make the regex simple, Doxray 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 updating by passing in a regex key to the options argument using the format seen in
https://github.com/himedlooff/doxray/blob/master/doxray.js#L12-L25
`js`
var docs = doxray(['styles.less'], {
jsFile: 'styles.js',
jsonFile: 'styles.json',
regex: {
css: {
opening: /^\/\\s@docs[^\n]*\n/m,
closing: /\*\//,
comment: /^\/\\s@docs[^]\+(?:[^/][^]\+)\//gm,
ignore: /^\/\\s@ignore-docs[\s\S]*/gm
}
}
});
##### The ignore-doxray comment can be used to indicate the end of a code pattern
This is helpful in cases where not every piece of code is documented; for example:
`css
/* doxray
name: button, duh
*/
.btn { ... }
/ end-doxray /
/ Some other code you don't want to document /
...
/* doxray
name: a different button or thing you want to document
*/
.btn__different { ... }
`
#### YAML structure
You can structure the YAML within the Doxray 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 Doxray 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 Doxray. For example
`js`
var doxray = require('doxray');
var docs = doxray(['styles.less'], { processors: [] });
Once Doxray parses the data it can run processing functions to manipulate the
data. Doxray runs two processors out of the box.
#### Slugify
If you use the label property in your Doxray comment the Slugify processorslug
will use that value to create a 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
Doxray will generate color palette data automatically if you specify a
colorPalette property in your Doxray comment. All you need to do is set thecolorPalette
value of the 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" }
]
}
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.
----
This projected is licensed under the terms of the MIT license.
----
This project was inspired by topdoc.
:smile: