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

Install

$ npm install dox-ray

Usage (as a node module)

First, you'll need a file to parse

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

styles.less:

/* doxray
label: Button
markup: <button class="btn">Button</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

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

In the above example, docs is equal to the following:

[
  {
    "label": "Button",
    "markup": "<button class=\"btn\">Button</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

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

styles.js:

Doxray = {
  "patterns": [
    {
      "label": "Button",
      "markup": "<button class=\"btn\">Button</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:

[
  {
    "label": "Button",
    "markup": "<button class=\"btn\">Button</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}"
  }
]

Dox-ray comment formatting

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.

<!-- doxray
label: my pattern
description: this is how you structure my pattern
-->

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

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

Processors

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:

/* doxray
label: Primary Button
*/

Will automatically parse to this:

{
  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:

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

Will automatically parse to this:

{
  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:

$ 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: