Skip to content

Commit

Permalink
Fixes to documentation generation
Browse files Browse the repository at this point in the history
  • Loading branch information
@christkv
christkv committed Dec 4, 2013
1 parent b74e698 commit 4f1b1a6
Show file tree
Hide file tree
Showing 6 changed files with 444 additions and 265 deletions.
168 changes: 85 additions & 83 deletions dev/tools/build-docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@ var apiClasses = [
{tag:"server", path:"./lib/mongodb/connection/server.js"},
{tag:"mongos", path:"./lib/mongodb/connection/mongos.js"},
{tag:"replset", path:"./lib/mongodb/connection/repl_set/repl_set.js"},
{tag:"readpreference", path:"./lib/mongodb/connection/read_preference.js"}
];
{tag:"readpreference", path:"./lib/mongodb/connection/read_preference.js"},
{tag:"ordered", path:"./lib/mongodb/collection/batch/ordered.js"},
{tag:"unordered", path:"./lib/mongodb/collection/batch/unordered.js"}
];

// All test files
var testClasses = [];
Expand Down Expand Up @@ -83,87 +85,87 @@ var outputDirectory = "./docs/sphinx-docs/source/api-generated"
// ----------------------------------------------------------------------------
docs.renderAPIDocs(outputDirectory, apiClasses, testClasses, templates, {index_title:'Driver API'});

// ----------------------------------------------------------------------------
// PROCESS BSON API
// ----------------------------------------------------------------------------
// Output directory
var outputDirectory2 = "./docs/sphinx-docs/source/api-bson-generated"
// Force create the directory for the generated docs
exec('rm -rf ' + outputDirectory2, function (error, stdout, stderr) {});
exec('mkdir ' + outputDirectory2, function (error, stdout, stderr) {});

var apiClasses2 = [
{tag:"objectid", path:"./node_modules/bson/lib/bson/objectid.js"},
{tag:"binary", path:"./node_modules/bson/lib/bson/binary.js"},
{tag:"code", path:"./node_modules/bson/lib/bson/code.js"},
{tag:"db_ref", path:"./node_modules/bson/lib/bson/db_ref.js"},
{tag:"double", path:"./node_modules/bson/lib/bson/double.js"},
{tag:"minkey", path:"./node_modules/bson/lib/bson/min_key.js"},
{tag:"maxkey", path:"./node_modules/bson/lib/bson/max_key.js"},
{tag:"symbol", path:"./node_modules/bson/lib/bson/symbol.js"},
{tag:"timestamp", path:"./node_modules/bson/lib/bson/timestamp.js"},
{tag:"long", path:"./node_modules/bson/lib/bson/long.js"},
{tag:"bson", path:"./node_modules/bson/lib/bson/bson.js"}
];

// Render the API docs
docs.renderAPIDocs(outputDirectory2, apiClasses2, testClasses, templates, {index_title:'Binary JSON API'});

// process.exit(0)

// ----------------------------------------------------------------------------
// PROCESS MARKDOWN DOCUMENTS TO STRUCTURED TEXT
// ----------------------------------------------------------------------------
// Transform the versionb based content
var articles = [
{name:"MongoClient", output:"MongoClient.rst", path:"./docs/articles/MongoClient.md"},
{name:"AnIntroductionTo1_1And2_2", output:"AnIntroductionTo1_1And2_2.rst", path:"./docs/articles/AnIntroductionTo1_1And2_2.md"}
];

// Tranform the markdown to restructured text
docs.writeMarkDownFile("./docs/sphinx-docs/source/driver-articles", articles, templates,
{title:'Updates', template:'index'});

// Transform the tutorials
var articles = [
{name:"NodeKOArticle1", output:"NodeKOArticle1.rst", path:"./docs/articles/NodeKOArticle1.md"},
{name:"NodeKOArticle2", output:"NodeKOArticle2.rst", path:"./docs/articles/NodeKOArticle2.md"}
];

// Tranform the markdown to restructured text
docs.writeMarkDownFile("./docs/sphinx-docs/source/api-articles", articles, templates,
{title:'Articles', template:'index'});

// Transform the tutorials
var articles = [
{name:"collections", output:"collections.rst", path:"./docs/collections.md"},
{name:"gridfs", output:"gridfs.rst", path:"./docs/gridfs.md"},
{name:"indexes", output:"indexes.rst", path:"./docs/indexes.md"},
{name:"insert", output:"insert.rst", path:"./docs/insert.md"},
{name:"queries", output:"queries.rst", path:"./docs/queries.md"}
];

// Tranform the markdown to restructured text
docs.writeMarkDownFile("./docs/sphinx-docs/source/markdown-docs", articles, templates,
{title:'Using the driver', template:'index_no_header'});

// ----------------------------------------------------------------------------
// WRITE CHANGELOG TO THE DOCUMENTATION
// ----------------------------------------------------------------------------
// Outputdiectory
var outputDirectoryChangelog = "./docs/sphinx-docs/source/changelog";
// Force create the directory for the generated docs
exec('rm -rf ' + outputDirectoryChangelog, function (error, stdout, stderr) {});
exec('mkdir ' + outputDirectoryChangelog, function (error, stdout, stderr) {
// Read all the templates
var templateObjects = docs.readAllTemplates(templates);
// Read the changelog
var changelog = fs.readFileSync('./HISTORY').toString();
// Just write out the index
var content = ejs.render(templateObjects["changelog"], {content:changelog});
// Write it out
fs.writeFileSync(format("%s/changelog.rst", outputDirectoryChangelog), content);
});
// // ----------------------------------------------------------------------------
// // PROCESS BSON API
// // ----------------------------------------------------------------------------
// // Output directory
// var outputDirectory2 = "./docs/sphinx-docs/source/api-bson-generated"
// // Force create the directory for the generated docs
// exec('rm -rf ' + outputDirectory2, function (error, stdout, stderr) {});
// exec('mkdir ' + outputDirectory2, function (error, stdout, stderr) {});

// var apiClasses2 = [
// {tag:"objectid", path:"./node_modules/bson/lib/bson/objectid.js"},
// {tag:"binary", path:"./node_modules/bson/lib/bson/binary.js"},
// {tag:"code", path:"./node_modules/bson/lib/bson/code.js"},
// {tag:"db_ref", path:"./node_modules/bson/lib/bson/db_ref.js"},
// {tag:"double", path:"./node_modules/bson/lib/bson/double.js"},
// {tag:"minkey", path:"./node_modules/bson/lib/bson/min_key.js"},
// {tag:"maxkey", path:"./node_modules/bson/lib/bson/max_key.js"},
// {tag:"symbol", path:"./node_modules/bson/lib/bson/symbol.js"},
// {tag:"timestamp", path:"./node_modules/bson/lib/bson/timestamp.js"},
// {tag:"long", path:"./node_modules/bson/lib/bson/long.js"},
// {tag:"bson", path:"./node_modules/bson/lib/bson/bson.js"}
// ];

// // Render the API docs
// docs.renderAPIDocs(outputDirectory2, apiClasses2, testClasses, templates, {index_title:'Binary JSON API'});

// // process.exit(0)

// // ----------------------------------------------------------------------------
// // PROCESS MARKDOWN DOCUMENTS TO STRUCTURED TEXT
// // ----------------------------------------------------------------------------
// // Transform the versionb based content
// var articles = [
// {name:"MongoClient", output:"MongoClient.rst", path:"./docs/articles/MongoClient.md"},
// {name:"AnIntroductionTo1_1And2_2", output:"AnIntroductionTo1_1And2_2.rst", path:"./docs/articles/AnIntroductionTo1_1And2_2.md"}
// ];

// // Tranform the markdown to restructured text
// docs.writeMarkDownFile("./docs/sphinx-docs/source/driver-articles", articles, templates,
// {title:'Updates', template:'index'});

// // Transform the tutorials
// var articles = [
// {name:"NodeKOArticle1", output:"NodeKOArticle1.rst", path:"./docs/articles/NodeKOArticle1.md"},
// {name:"NodeKOArticle2", output:"NodeKOArticle2.rst", path:"./docs/articles/NodeKOArticle2.md"}
// ];

// // Tranform the markdown to restructured text
// docs.writeMarkDownFile("./docs/sphinx-docs/source/api-articles", articles, templates,
// {title:'Articles', template:'index'});

// // Transform the tutorials
// var articles = [
// {name:"collections", output:"collections.rst", path:"./docs/collections.md"},
// {name:"gridfs", output:"gridfs.rst", path:"./docs/gridfs.md"},
// {name:"indexes", output:"indexes.rst", path:"./docs/indexes.md"},
// {name:"insert", output:"insert.rst", path:"./docs/insert.md"},
// {name:"queries", output:"queries.rst", path:"./docs/queries.md"}
// ];

// // Tranform the markdown to restructured text
// docs.writeMarkDownFile("./docs/sphinx-docs/source/markdown-docs", articles, templates,
// {title:'Using the driver', template:'index_no_header'});

// // ----------------------------------------------------------------------------
// // WRITE CHANGELOG TO THE DOCUMENTATION
// // ----------------------------------------------------------------------------
// // Outputdiectory
// var outputDirectoryChangelog = "./docs/sphinx-docs/source/changelog";
// // Force create the directory for the generated docs
// exec('rm -rf ' + outputDirectoryChangelog, function (error, stdout, stderr) {});
// exec('mkdir ' + outputDirectoryChangelog, function (error, stdout, stderr) {
// // Read all the templates
// var templateObjects = docs.readAllTemplates(templates);
// // Read the changelog
// var changelog = fs.readFileSync('./HISTORY').toString();
// // Just write out the index
// var content = ejs.render(templateObjects["changelog"], {content:changelog});
// // Write it out
// fs.writeFileSync(format("%s/changelog.rst", outputDirectoryChangelog), content);
// });

// ----------------------------------------------------------------------------
// Generate using the driver pages
Expand Down
10 changes: 8 additions & 2 deletions dev/tools/doc-templates/class.ejs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ for(var i = 0; i < entries.length; i++) {
for(var ti = 0; ti < entries[i].tags.length; ti++) {
// Get the current tag
var tag = entries[i].tags[ti];
// If we have a parameter render it
if(tag.type == 'param') {
// Unpack the tag
Expand Down Expand Up @@ -200,7 +201,7 @@ for(var i = 0; i < entries.length; i++) {
}
}
for(var i = 0; i < entries.length; i++) {
for(var i = 0; i < entries.length; i++) {
// If it's a function parse it
if(isFunction(entries[i])) {
var paramsStrings = [];
Expand All @@ -209,6 +210,7 @@ for(var i = 0; i < entries.length; i++) {
for(var ti = 0; ti < entries[i].tags.length; ti++) {
// Get the current tag
var tag = entries[i].tags[ti];
// If we have a parameter render it
if(tag.type == 'param') {
// Unpack the tag
Expand All @@ -230,6 +232,7 @@ for(var i = 0; i < entries.length; i++) {
// Reformat any optional parameters from ,[] to [,]
var paramsString = paramNames.join(", ").replace(/\, \[/, "[, ");
// Write out the methods
var fullDescription = entries[i].description.full;
Expand All @@ -246,7 +249,7 @@ for(var i = 0; i < entries.length; i++) {
var examplesName = entries[i].ctx.name;
// Write header depending on if it's class or instance level
if(entries[i].ctx.receiver != null) {
if(entries[i].ctx.receiver != "this") {
// Change examples Name to include class name
var examplesName = format("%s.%s", className, entries[i].ctx.name);
var _length = format("%s.%s", className, entries[i].ctx.name).length;
Expand All @@ -266,10 +269,13 @@ for(var i = 0; i < entries.length; i++) {
if(examples != null && examples[examplesName]) {
%><%= format("\n**Examples**\n\n") %><%
var examplesArray = examples[examplesName];
// Iterate over all the examples
for(var ei = 0; ei < examplesArray.length; ei++) {
// Fetch an example
var example = examplesArray[ei];
var code = example.code;
code = code.replace(", ssl:useSSL", "")
.replace("native_parser: native_parser", "native_parser: false")
Expand Down
46 changes: 37 additions & 9 deletions dev/tools/docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,15 +159,11 @@ exports.buildTestHash = function(objects) {
}
}

// console.log(codeLines)

codeLines = codeLines.slice(start, end);
codeLines = additional_lines.concat(codeLines);
// Reasign the code block

// Reassign the code block
block.code = codeLines.join("\n");

// console.log("------------------------------------------- CODE")
// console.log(block.code)
}
}
}
Expand All @@ -187,7 +183,31 @@ exports.renderAllTemplates = function(outputDirectory, templates, dataObjects, t
}

var isFunction = function(entry) {
return entry.ctx != null && entry.ctx.type == 'method' && entry.isPrivate == false;
console.log("============================================== classMetaData")
console.log(JSON.stringify(entry, true, 4))

// If we have a context
if(entry.ctx != null
&& (entry.ctx.type == 'method' || entry.ctx.type == 'function')
&& entry.isPrivate == false
&& entry.tags.length >= 1
&& entry.tags[0].type == 'param') {
return true;
}

// // If no context but a param
// if(entry.isPrivate == false
// && entry.tags.length >= 1
// && entry.tags[0].type == 'param') {
// return true;
// }

return false;
// return entry.ctx != null
// && (entry.ctx.type == 'method' || entry.ctx.type == 'function')
// && entry.isPrivate == false
// && entry.tags.length >= 1
// && entry.tags[0].type == 'param';
}

var isProperty = function(entry) {
Expand All @@ -214,12 +234,20 @@ exports.renderAllTemplates = function(outputDirectory, templates, dataObjects, t
var className = classNames[i];
// The meta data object
var classMetaData = dataObjects[className];
// console.log("============================================== classMetaData")
// console.log(JSON.stringify(classMetaData, true, 4))

// Grab the examples for this Metadata class
var classExamplesData = testObjects[className];
// Render the class template
var classContent = ejs.render(templates['class'],
{entries:classMetaData, examples:classExamplesData, isClass:isClass,
isFunction:isFunction, isProperty:isProperty, isClassConstant:isClassConstant,
{
entries: classMetaData
, examples: classExamplesData
, isClass: isClass
, isFunction: isFunction
, isProperty: isProperty
, isClassConstant: isClassConstant,
format:format});
// Write out the content to disk
fs.writeFileSync(format("%s/%s.rst", outputDirectory, className), classContent);
Expand Down
4 changes: 2 additions & 2 deletions lib/mongodb/collection.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -624,7 +624,7 @@ Collection.prototype.stats = function() { return commands.stats; }();
*
* @param {Objects} [options] options for the initializeUnorderedBatch
* @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. The second argument will be a UnorderedBulkOperation object.
* @return {null}
* @return {UnorderedBulkOperation}
* @api public
*/
Collection.prototype.initializeUnorderedBulkOp = function() { return unordered.initializeUnorderedBulkOp; }();
Expand All @@ -640,7 +640,7 @@ Collection.prototype.initializeUnorderedBulkOp = function() { return unordered.i
*
* @param {Objects} [options] options for the initializeOrderedBulkOp
* @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. The second argument will be a OrderedBulkOperation object.
* @return {null}
* @return {OrderedBulkOperation}
* @api public
*/
Collection.prototype.initializeOrderedBulkOp = function() { return ordered.initializeOrderedBulkOp; }();
Expand Down
Loading

0 comments on commit 4f1b1a6

Please sign in to comment.