0.6.1 • Published 10 years ago

dox-ray v0.6.1

Weekly downloads
42
License
MIT
Repository
github
Last release
10 years ago

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

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

0.6.1

10 years ago

0.6.0

10 years ago

0.5.2

10 years ago

0.5.1

10 years ago

0.5.0

10 years ago

0.4.3

10 years ago

0.4.2

10 years ago

0.4.1

10 years ago

0.4.0

10 years ago

0.3.2

11 years ago

0.3.1

11 years ago

0.3.0

11 years ago

0.2.0

11 years ago

0.1.1

11 years ago

0.1.0

11 years ago