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 https://github.com/himedlooff/doxray-template.

Note that this project is currently in Beta.

Getting started

Install

$ npm install doxray

Usage (as a node module)

First, you'll need a file to parse

Here's how you write a Doxray 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 Doxray to parse stuff

var doxray = require('doxray');
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 using the second argument to pass options

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}"
  }
]

Doxray comment formatting

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.

<!-- 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 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

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:

/* 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

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

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

Doxray will generate color palette data automatically if you specify a colorPalette property in your Doxray 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: