Skip to content

Commit

Permalink
Add -p/-package option to ringo-doc to allow adjusting module names a…
Browse files Browse the repository at this point in the history 
…ccording to package loading conventions.
  • Loading branch information
@hns
hns committed Feb 22, 2012
1 parent 20c888b commit 5f6999a
Show file tree
Hide file tree
Showing 6 changed files with 78 additions and 57 deletions.
36 changes: 23 additions & 13 deletions tools/jsdoc/jsdocserializer.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,35 +28,45 @@ var getRepositoryName = exports.getRepositoryName = function(repositoryOrPath) {

/**
* Returns a name sorted, stringify-able list of objects describing the
* modules for the given repositoryPath.
* modules for the given repository.
*
* @param {String} repositoryPath
* @param {Object} repository repository descriptor
* @param {Boolean} moduleFileOverview if true every module will be parsed and
* it's fileoverview attached. default: false.
* @returns {Array} modules
*/
var moduleList = exports.moduleList = function(repositoryPath, moduleFileOverview) {
var repository = new ScriptRepository(repositoryPath);
var modules = repository.getScriptResources(true).filter(function(r) {
var moduleList = exports.moduleList = function(repository, moduleFileOverview) {
var packageName = repository.package.name;
var mainModule = repository.package.main;
var scriptRepository = new ScriptRepository(repository.path);
return scriptRepository.getScriptResources(true).filter(function(r) {
return !r.moduleName.match(/^ringo\/?global$/);
}).map(function(mod) {
var fileoverview = undefined;
if (moduleFileOverview) {
var docItems = parseResource(mod);
fileoverview = docItems.fileoverview && docItems.fileoverview.getTag('fileoverview') || '';
}
var id = mod.moduleName.replace(/\./g,'/');
var name = id;
// If this is a package adjust module names according to package loading
// conventions: use just the package name for main module and prepend
// the package name to all other modules.
if (mainModule && mainModule == mod)
name = packageName || name;
else if (packageName && packageName != id)
name = packageName + '/' + id;
return {
id: mod.moduleName.replace(/\./g,'/'),
id: id,
name: name,
fileoverview: fileoverview
}
}).sort(function(a, b) {
// sort modules by namespace depth first, then lexographically
var level = strings.count(a.id, '/') - strings.count(b.id, '/');
var level = strings.count(a.name, '/') - strings.count(b.name, '/');
if (level != 0) return level;
return a.id > b.id ? 1 : -1;
return a.name > b.name ? 1 : -1;
});

return modules;
};

/**
Expand All @@ -74,16 +84,16 @@ var repositoryList = exports.repositoryList = function(repositoryPaths) {
/**
* @returns {Array} objects with jsdoc information for each property defined in module
*/
var moduleDoc = exports.moduleDoc = function(repositoryPath, moduleId, toLink) {
var moduleDoc = exports.moduleDoc = function(repositoryPath, module, toLink) {
var repository = new ScriptRepository(repositoryPath);
var res = repository.getScriptResource(moduleId + '.js');
var res = repository.getScriptResource(module.id + '.js');
if (!res.exists()) {
return null;
}
var docItems = parseResource(res);

var doc = {};
doc.name = moduleId;
doc.name = module.name;
if (docItems.fileoverview) {
doc.fileoverview = docItems.fileoverview.getTag('fileoverview');
doc.example = docItems.fileoverview.getTag('example');
Expand Down
91 changes: 51 additions & 40 deletions tools/jsdoc/main.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,8 @@

// stdlib
var files = require('ringo/utils/files');
var {makeTree, write, copyTree, join, Path} = require('fs');
var fs = require('fs');
var {Parser} = require('ringo/args');
var {isFile, isDirectory} = require('fs');
var {ScriptRepository} = require('ringo/jsdoc');
var strings = require('ringo/utils/strings');
var objects = require('ringo/utils/objects');
Expand All @@ -30,30 +29,30 @@ var templates = {
};

/**
* Renders jsdoc html files for the given repository into the exportDirectory.
* Renders jsdoc html files for the given repository into the given directory.
*
* @param {Object} repository
* @param {String} exportDirectory
* @param {String} directory
* @param {Boolean} quiet
*/
var renderRepository = exports.renderRepository = function (repository, exportDirectory, quiet) {
var renderRepository = exports.renderRepository = function (repository, directory, quiet) {
// need apps/jsdoc on path for skin extend to work
if (require.paths.indexOf(module.directory) == -1) {
require.paths.push(module.directory);
}

if (!quiet) print ('Writing to ' + exportDirectory + '...');
copyStaticFiles(exportDirectory);
if (!quiet) print ('Writing to ' + directory + '...');
copyStaticFiles(directory);
if (!quiet) print ('Module index');
writeRepositoryIndex(exportDirectory, repository);
writeRepositoryIndex(directory, repository);
if (!quiet) print(repository.path);
writeModuleList(exportDirectory, repository);
moduleList(repository.path).forEach(function(module) {
if (!quiet) print('\t' + module.id);
writeModuleDoc(exportDirectory, repository, module.id);
writeModuleList(directory, repository);
moduleList(repository).forEach(function(module) {
if (!quiet) print('\t' + module.name);
writeModuleDoc(directory, repository, module);
});

if (!quiet) print('Finished writing to ' + exportDirectory);
if (!quiet) print('Finished writing to ' + directory);
return;
}

Expand All @@ -63,21 +62,21 @@ var renderRepository = exports.renderRepository = function (repository, exportDi
* @param {String} directory
*/
function copyStaticFiles(directory) {
makeTree(join(directory, 'static'));
copyTree(join(module.directory, 'static'), join(directory, 'static'));
fs.makeTree(fs.join(directory, 'static'));
fs.copyTree(fs.join(module.directory, 'static'), fs.join(directory, 'static'));
}

/**
* Write the html file listing all modules to directory.
*
* @param {String} directory directory of html file to be written
* @param {String} repository path
* @param {Object} repository repository descriptor
*/
function writeModuleList(directory, repository) {
var context = objects.merge(defaultContext, {
repositoryName: repository.name,
title: 'Module overview - ' + repository.name,
modules: moduleList(repository.path, true),
modules: moduleList(repository, true),
rootPath: './',
markdown: function(text) {
return markdown.process(text);
Expand All @@ -88,25 +87,25 @@ function writeModuleList(directory, repository) {
context.menu = mustache.to_html(templates.menu, context);
context.content = mustache.to_html(templates.repository, context);
var repositoryHtml = mustache.to_html(templates.page, context);
write(join(directory, 'index.html'), repositoryHtml);
fs.write(fs.join(directory, 'index.html'), repositoryHtml);
}

/**
* Write html page documenting one module to the directory.
*
* @param {String} directory
* @param {String} repository path
* @param {String} moduleId
* @param {Object} repository repository descriptor
* @param {Object} module module descriptor
*/
function writeModuleDoc(directory, repository, moduleId){
function writeModuleDoc(directory, repository, module){

var moduleDirectory = directory;
var modules = [];
moduleDirectory = join(directory, moduleId);
makeTree(moduleDirectory);
modules = moduleList(repository.path);
moduleDirectory = fs.join(directory, module.id);
fs.makeTree(moduleDirectory);
modules = moduleList(repository);

var slashCount = strings.count(moduleId, '/');
var slashCount = strings.count(module.id, '/');
var relativeRoot = '../' + strings.repeat('../', slashCount);

function toLink(target) {
Expand All @@ -125,16 +124,16 @@ function writeModuleDoc(directory, repository, moduleId){
return null;
}

var docs = moduleDoc(repository.path, moduleId, toLink);
var docs = moduleDoc(repository.path, module, toLink);
if (docs == null) {
throw new Error('Could not parse JsDoc for ' + repository.path + moduleId);
throw new Error('Could not parse JsDoc for ' + repository.path + module.id);
}

var context = objects.merge(defaultContext, {
rootPath: relativeRoot,
repositoryName: repository.name,
title: moduleId + ' - ' + repository.name,
moduleId: moduleId,
title: module.name + ' - ' + repository.name,
moduleId: module.id,
modules: modules,
item: structureModuleDoc(docs),
paramList: function() {
Expand All @@ -161,13 +160,13 @@ function writeModuleDoc(directory, repository, moduleId){
context.menu = mustache.to_html(templates.menu, context);
context.content = mustache.to_html(templates.module, context);
var moduleHtml = mustache.to_html(templates.page, context);
var moduleFile = join(moduleDirectory, 'index.html');
write(moduleFile, moduleHtml);
var moduleFile = fs.join(moduleDirectory, 'index.html');
fs.write(moduleFile, moduleHtml);
}

function writeRepositoryIndex(directory, repository) {
var modules = moduleList(repository.path).map(function(module) {
module.data = structureModuleDoc(moduleDoc(repository.path, module.id));
var modules = moduleList(repository).map(function(module) {
module.data = structureModuleDoc(moduleDoc(repository.path, module));
module.moduleName = module.name;
return module;
});
Expand All @@ -187,8 +186,8 @@ function writeRepositoryIndex(directory, repository) {
context.menu = mustache.to_html(templates.menu, context);
context.content = mustache.to_html(templates.index, context);
var indexHtml = mustache.to_html(templates.page, context);
var indexFile = join(directory, 'index_all.html');
write(indexFile, indexHtml);
var indexFile = fs.join(directory, 'index_all.html');
fs.write(indexFile, indexHtml);
}

/**
Expand Down Expand Up @@ -223,6 +222,7 @@ function main(args) {
parser.addOption('t', 'template', 'file', 'Master template to use');
parser.addOption('n', 'name', 'name', 'Name of the Repository (default: auto generated from path)');
parser.addOption('q', 'quiet', null, 'Do not output any messages.');
parser.addOption('p', 'package', 'package.json', 'Use package manifest to adjust module names.')
parser.addOption(null, 'file-urls', null, 'Add "index.html" to all URLs for file:// serving.');
parser.addOption('h', 'help', null, 'Print help message and exit');

Expand All @@ -242,27 +242,38 @@ function main(args) {
templates.page = t.content;
}

var exportDirectory = join(opts.directory || './out/');
if (opts.package) {
// read package.json manifest
var packageJson = fs.absolute(opts.package);
var pkg = opts.package = require(packageJson);
if (pkg.main) {
// make main module absolute
pkg.main = fs.absolute(fs.join(fs.directory(packageJson), pkg.main))
}
}

var directory = fs.join(opts.directory || './out/');
var repository = {
path: opts.source,
name: opts.name || getRepositoryName(opts.source)
name: opts.name || getRepositoryName(opts.source),
package: opts.package || {}
};
var quiet = opts.quiet || false;
defaultContext.indexhtml = opts['fileUrls'] ? 'index.html' : '';

// check if export dir exists & is empty
var dest = new Path(exportDirectory);
var dest = new fs.Path(directory);
if (dest.exists() && !dest.isDirectory()) {
throw new Error(dest + ' exists but is not a directory.');
} else if (dest.isDirectory() && dest.list().length > 0) {
throw new Error('Directory ' + dest + ' exists but is not empty');
}

if (!isDirectory(repository.path)) {
if (!fs.isDirectory(repository.path)) {
throw new Error('Invalid source specified. Must be directory.');
}

renderRepository(repository, exportDirectory, quiet);
renderRepository(repository, directory, quiet);
}

if (require.main == module) {
Expand Down
2 changes: 1 addition & 1 deletion tools/jsdoc/templates/index_all.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ <h1>{{title}}</h1>

{{#modules}}
<div class="modulecontainer">
<h2 class="modulename">Module <a href="./{{id}}">{{id}}</a></h2>
<h2 class="modulename">Module <a href="{{rootPath}}{{id}}/{{indexhtml}}">{{name}}</a></h2>
{{#data}}
<ul class="propertyoverview">

Expand Down
2 changes: 1 addition & 1 deletion tools/jsdoc/templates/menu.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
<input id="jsdoc-leftnavsearch" type="search" placeholder="Filter module list" size="14">
<ul class="jsdoc-leftnav leftnav">
{{#modules}}
<li><a href="{{rootPath}}{{id}}/{{indexhtml}}"> {{id}} </a></li>
<li><a href="{{rootPath}}{{id}}/{{indexhtml}}"> {{name}} </a></li>
{{/modules}}
</ul>
2 changes: 1 addition & 1 deletion tools/jsdoc/templates/module.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<div class="main">
<div class="content">
{{#item}}
<h1 class="modulename">Module {{moduleId}}</h1>
<h1 class="modulename">Module {{name}}</h1>
<div class="fileoverview">
{{{markdown fileoverview}}}
</div>
Expand Down
2 changes: 1 addition & 1 deletion tools/jsdoc/templates/repository.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ <h1>Modules: {{repositoryName}}</h1>
{{#modules}}
<li >

<h2><a href="{{rootPath}}{{id}}/{{indexhtml}}"> {{id}} </a></h2>
<h2><a href="{{rootPath}}{{id}}/{{indexhtml}}"> {{name}} </a></h2>
<div class="jsdoc-fileoverview">
{{{markdown fileoverview}}}
</div>
Expand Down

0 comments on commit 5f6999a

Please sign in to comment.