Initial commit

Author: auscaster

.gitignore

@@ -0,0 +1 @@
+node_modules/

LICENCE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Original work Copyright (c) 2016 Philippe FERDINAND
+Modified work Copyright (c) 2016 Kam Low
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,27 @@
+# Moxygen
+
+Moxygen is a doxygen XML to markdown converter that fills the need for developers who have been craving a beautiful and minimal documentation alternative for their C++ projects.
+
+The code is a heavily modified port of `doxygen2md` with a focus on generating multi page documentation from doxygen [modules](http://www.stack.nl/~dimitri/doxygen/manual/grouping.html#modules).
+
+Moxygen is the API documentation generator used by LibSourcey, the result of which can be seen [here](http://sourcey.com/libsourcey/).
+
+## Usage
+
+1. Run `doxygen` to generate the XML documentation.
+2. Run `moxygen` providing the folder location of the XML documentation.  
+
+  ```
+  Usage: moxygen [options] <doxygen directory>
+
+  Options:
+
+    -h, --help             output usage information
+    -V, --version          output the version number
+    -v, --verbose          verbose mode
+    -a, --anchors          add anchors to internal links
+    -g, --modules          output doxygen modules into separate files
+    -l, --language <lang>  programming language
+    -t, --templates <dir>  custom templates directory
+    -o, --output <file>    output file (must contain %s when using modules)
+  ```

bin/moxygen.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+var log = require('winston');
+var program = require('commander');
+var assign = require('object-assign');
+var pjson = require('../package.json');
+var app = require('../index.js');
+
+program.version(pjson.version)
+  .usage('[options] <doxygen directory>')
+  .option('-v, --verbose', 'verbose mode', false)
+  .option('-a, --anchors', 'add anchors to internal links', false)
+  .option('-g, --modules', 'output doxygen modules into separate files', false)
+  .option('-l, --language <lang>', 'programming language', String, 'cpp')
+  .option('-t, --templates <dir>', 'custom templates directory', String, 'templates')
+  .option('-o, --output <file>', 'output file (must contain %s when using modules)', String, 'api.md')
+  .parse(process.argv);
+
+if (program.verbose) {
+  log.level = 'verbose';
+}
+
+if (program.args.length) {
+  app.run(assign({}, app.defaultOptions, {
+    directory: program.args[0],
+    anchors: program.anchors,
+    modules: program.modules,
+    language: program.language,
+    templates: program.templates,
+    output: program.output
+  }));
+}
+else {
+  program.help();
+}

index.js

@@ -0,0 +1,89 @@
+/**
+ * Original work Copyright (c) 2016 Philippe FERDINAND
+ * Modified work Copyright (c) 2016 Kam Low
+ *
+ * @license MIT
+ **/
+'use strict';
+
+var path = require('path');
+var util = require('util');
+
+var doxyparser = require('./src/parser');
+var templates = require('./src/templates');
+var helpers = require('./src/helpers');
+
+module.exports = {
+
+  /**
+   * Default options values.
+   **/
+  defaultOptions: {
+
+    directory: null,            /** Location of the doxygen files **/
+    anchors: true,              /** Generate anchors for internal links **/
+    groups: true,               /** Output doxygen groups separately **/
+    language: 'cpp',            /** Programming language **/
+    templates: 'templates',     /** Templates directory **/
+    output: 'api.md',           /** Output file **/
+
+    filters: {
+      members: [
+        'public-attrib',
+        'public-func',
+        'protected-attrib',
+        'protected-func'
+      ],
+      compounds: [
+        'namespace',
+        'class',
+        'struct',
+        'union',
+        'typedef'
+      ]
+    }
+  },
+
+  /**
+   * Parse files and render the output.
+   **/
+  run: function (options) {
+
+    // Sanitize options
+    if (options.groups == options.output.indexOf('%s') === -1)
+      throw "The `output` file parameter must contain an '%s' for group name" +
+        "substitution when `groups` are enabled."
+
+    if (options.templates == this.defaultOptions.templates)
+      options.templates = path.join(__dirname, 'templates', options.language);
+
+    // Load templates
+    templates.registerHelpers(options);
+    templates.load(options.templates);
+
+    // Parse files
+    doxyparser.loadIndex(options, function (err, root) {
+
+      // Output groups
+      if (options.groups) {
+        root.toArray('compounds', 'group').forEach(function (group) {
+          group.filterChildren(options.filters, group.id);
+
+          var compounds = group.toFilteredArray('compounds');
+          compounds.unshift(group); // insert group at top
+          var contents = templates.renderArray(compounds);
+          helpers.writeFile(util.format(options.output, group.name), contents);
+        });
+      }
+
+      // Output single file
+      else {
+        root.filterChildren(options.filters);
+
+        var compounds = root.toFilteredArray('compounds');
+        var contents = templates.renderArray(compounds);
+        helpers.writeFile(options.output, contents);
+      }
+    });
+  }
+}

package.json

@@ -0,0 +1,30 @@
+{
+  "name": "moxygen",
+  "version": "0.5.0",
+  "description": "Doxygen XML to Markdown documentation converter",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bin": {
+    "doxygen2md": "./bin/moxygen.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sourcey/moxygen.git"
+  },
+  "keywords": [
+    "doxygen",
+    "markdown",
+    "documentation"
+  ],
+  "author": "Kam Low",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^2.9.0",
+    "handlebars": "^4.0.5",
+    "object-assign": "^4.1.0",
+    "winston": "^2.2.0",
+    "xml2js": "^0.4.16"
+  }
+}

src/compound.js

@@ -0,0 +1,108 @@
+/**
+ * Original work Copyright (c) 2016 Philippe FERDINAND
+ * Modified work Copyright (c) 2016 Kam Low
+ *
+ * @license MIT
+ **/
+'use strict';
+
+var log = require('winston');
+
+function Compound(parent, name) {
+  this.parent = parent;
+  this.name = name;
+  this.compounds = {};
+  this.members = [];
+  this.basecompoundref = [];
+  this.filtered = {};
+}
+
+Compound.prototype = {
+
+  find: function (name, create) {
+    var compound = this.compounds[name];
+
+    if (!compound && create) {
+      compound = this.compounds[name] = new Compound(this, name);
+    }
+
+    return compound;
+  },
+
+  toArray: function (type, kind) {
+    type = type || 'compounds';
+    var arr = Object.keys(this[type]).map(function(key) {
+      return this[key];
+    }.bind(this[type]));
+
+    if (type == 'compounds') {
+      var all = new Array();
+      arr.forEach(function (compound) {
+        if (!kind || compound.kind == kind) { //compound &&
+          all.push(compound);
+          all = all.concat(compound.toArray(type, kind));
+        }
+      }.bind(this));
+      arr = all;
+    }
+
+    return arr;
+  },
+
+  toFilteredArray: function (type) {
+    type = type || 'compounds';
+    var all = [];
+
+    (this.filtered[type] || []).forEach(function (item) {
+      var children = item.toFilteredArray(type);
+      all.push(item);
+      all = all.concat(children);
+    });
+
+    return all;
+  },
+
+  filterChildren: function (filters, groupid) {
+    this.toArray('compounds').forEach(function (compound) {
+      compound.filtered.members = compound.filter(compound.members, 'section', filters.members, groupid);
+      compound.filtered.compounds = compound.filter(compound.compounds, 'kind', filters.compounds, groupid);
+    });
+    this.filtered.compounds = this.filter(this.compounds, 'kind', filters.compounds, groupid);
+  },
+
+  filter: function (collection, key, filter, groupid) {
+    var categories = {};
+    var result = [];
+
+    Object.keys(collection).forEach(function (name) {
+      var item = collection[name];
+      if (item) {
+
+        // skip empty namespaces
+        if (item.kind == 'namespace') {
+          if ((!item.filtered.compounds || !item.filtered.compounds.length) &&
+            (!item.filtered.members || !item.filtered.members.length)) {
+            // log.verbose('Skip empty namespace', item.name);
+            return;
+          }
+        }
+
+        // skip items not belonging to current group
+        else if (groupid && item.groupid != groupid) {
+          // log.verbose('Skip item from foreign group', item.kind, item.name, item.groupid, group.id);
+          return;
+        }
+
+        (categories[item[key]] || (categories[item[key]] = [])).push(item);
+      }
+    }.bind(this));
+
+    filter.forEach(function (category) {
+      result = result.concat(categories[category] || []);
+    });
+
+    return result;
+  }
+}
+
+module.exports = Compound;

src/helpers.js

@@ -0,0 +1,69 @@
+/**
+ * Original work Copyright (c) 2016 Philippe FERDINAND
+ * Modified work Copyright (c) 2016 Kam Low
+ *
+ * @license MIT
+ **/
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var util = require('util');
+var handlebars = require('handlebars');
+
+module.exports = {
+
+  inline: function(code) {
+    if (Array.isArray(code)) {
+      var refs, s = '', isInline = false;
+      code.forEach(function (e) {
+        refs = e.split(/(\[.*\]\(.*\)|\n|\s{2}\n)/g);
+        refs.forEach(function (f) {
+          if (f.charAt(0) == '[') {
+            // link
+            var link = f.match(/\[(.*)\]\((.*)\)/);
+            isInline ? (s += '`') && (isInline = false) : null;
+            s += '[`' + link[1] + '`](' + link[2] + ')';
+          }
+          else if (f == '\n' || f == '  \n') {
+            // line break
+            isInline ? (s += '`') && (isInline = false) : null;
+            s += f;
+          }
+          else if (f) {
+            !isInline ? (s += '`') && (isInline = true) : null;
+            s += f;
+          }
+        });
+      });
+      return s + (isInline ? '`' : '');
+    }
+    else {
+      return '`' + code + '`';
+    }
+  },
+
+  // Replace group links to point to correct output file
+  replaceGroupReflink: function (outfile, references, str) {
+    var match = str.match(/\((#(.*))\)/),
+      anchor = match[1],
+      refid = match[2],
+      ref = references[refid];
+    if (ref && ref.groupname) {
+      var href = util.format(outfile, ref.groupname) + anchor;
+      str = str.replace(/\((#(.*))\)/, '(' + href + ')')
+    }
+    return str;
+  },
+
+  // Write the output file
+  writeFile: function (filepath, contents) {
+    var stream = fs.createWriteStream(filepath);
+    stream.once('open', function(fd) {
+      contents.forEach(function (content) {
+        stream.write(content);
+      });
+      stream.end();
+    });
+  }
+};