Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Modifications to markdown docs to work better

  • Loading branch information...
commit 4a83019158b5b43b6e72ffead2ed3d06836602cb 1 parent a0105bb
@christkv christkv authored
View
158 dev/tools/build-docs.js
@@ -12,13 +12,13 @@ var fs = require('fs'),
// ----------------------------------------------------------------------------
// All source files for the api generation
var apiClasses = [
- // {tag:"admin", path:"./lib/mongodb/admin.js"},
- // {tag:"collection", path:"./lib/mongodb/collection.js"},
- // {tag:"db", path:"./lib/mongodb/db.js"},
- // {tag:"cursor", path:"./lib/mongodb/cursor.js"},
- // {tag:"cursorstream", path:"./lib/mongodb/cursorstream.js"},
- // {tag:"gridstore", path:"./lib/mongodb/gridfs/gridstore.js"},
- // {tag:"readstream", path:"./lib/mongodb/gridfs/readstream.js"},
+ {tag:"admin", path:"./lib/mongodb/admin.js"},
+ {tag:"collection", path:"./lib/mongodb/collection.js"},
+ {tag:"db", path:"./lib/mongodb/db.js"},
+ {tag:"cursor", path:"./lib/mongodb/cursor.js"},
+ {tag:"cursorstream", path:"./lib/mongodb/cursorstream.js"},
+ {tag:"gridstore", path:"./lib/mongodb/gridfs/gridstore.js"},
+ {tag:"readstream", path:"./lib/mongodb/gridfs/readstream.js"},
{tag:"grid", path:"./lib/mongodb/gridfs/grid.js"}
];
@@ -56,84 +56,84 @@ var templates = [
{tag:'function', path:'./dev/tools/doc-templates/function.ejs'}
]
-// // Output directory
-// var outputDirectory = "./docs/sphinx-docs/source/api-generated"
-//
-// // Force create the directory for the generated docs
-// exec('rm -rf ' + outputDirectory, function (error, stdout, stderr) {});
-// exec('mkdir ' + outputDirectory, function (error, stdout, stderr) {});
-//
-// // ----------------------------------------------------------------------------
-// // PROCESS Driver API
-// // ----------------------------------------------------------------------------
-// // Extract meta data from source files
-// var dataObjects = docs.extractLibraryMetaData(apiClasses);
-// // Filter out and prepare the test Objects hash
-// var testObjects = docs.buildTestHash(docs.extractLibraryMetaData(testClasses));
+// Output directory
+var outputDirectory = "./docs/sphinx-docs/source/api-generated"
+
+// Force create the directory for the generated docs
+exec('rm -rf ' + outputDirectory, function (error, stdout, stderr) {});
+exec('mkdir ' + outputDirectory, function (error, stdout, stderr) {});
+
+// ----------------------------------------------------------------------------
+// PROCESS Driver API
+// ----------------------------------------------------------------------------
+// Extract meta data from source files
+var dataObjects = docs.extractLibraryMetaData(apiClasses);
+// Filter out and prepare the test Objects hash
+var testObjects = docs.buildTestHash(docs.extractLibraryMetaData(testClasses));
// Read all the templates
var templates = docs.readAllTemplates(templates);
-// // Render all the classes that are decorated
-// docs.renderAllTemplates(outputDirectory, templates, dataObjects, testObjects, {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:"./lib/mongodb/bson/objectid.js"},
-// // {tag:"binary", path:"./lib/mongodb/bson/binary.js"},
-// // {tag:"code", path:"./lib/mongodb/bson/code.js"},
-// // {tag:"code", path:"./lib/mongodb/bson/db_ref.js"},
-// // {tag:"double", path:"./lib/mongodb/bson/double.js"},
-// // {tag:"maxkey", path:"./lib/mongodb/bson/max_key.js"},
-// // {tag:"symbol", path:"./lib/mongodb/bson/symbol.js"},
-// // {tag:"timestamp", path:"./lib/mongodb/bson/timestamp.js"},
-// // {tag:"long", path:"./lib/mongodb/bson/long.js"},
-// {tag:"bson", path:"./lib/mongodb/bson/bson.js"}
-// ];
-//
-// // Read all the templates
-// var templates2 = [
-// {tag:'index', path:'./dev/tools/doc-templates/index.ejs'},
-// {tag:'index_no_header', path:'./dev/tools/doc-templates/index_no_header.ejs'},
-// {tag:'class', path:'./dev/tools/doc-templates/class.ejs'},
-// {tag:'function', path:'./dev/tools/doc-templates/function.ejs'}
-// ]
-//
-// // Extract meta data from source files
-// var dataObjects2 = docs.extractLibraryMetaData(apiClasses2);
-// // Filter out and prepare the test Objects hash
-// var testObjects2 = docs.buildTestHash(docs.extractLibraryMetaData(testClasses));
-// // Render all the classes that are decorated
-// docs.renderAllTemplates(outputDirectory2, templates, dataObjects2, testObjects2, {index_title:'Binary JSON API'});
-//
-// // ----------------------------------------------------------------------------
-// // PROCESS MARKDOWN DOCUMENTS TO STRUCTURED TEXT
-// // ----------------------------------------------------------------------------
-//
-// // 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'});
+// Render all the classes that are decorated
+docs.renderAllTemplates(outputDirectory, templates, dataObjects, testObjects, {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:"./lib/mongodb/bson/objectid.js"},
+ {tag:"binary", path:"./lib/mongodb/bson/binary.js"},
+ {tag:"code", path:"./lib/mongodb/bson/code.js"},
+ {tag:"code", path:"./lib/mongodb/bson/db_ref.js"},
+ {tag:"double", path:"./lib/mongodb/bson/double.js"},
+ {tag:"maxkey", path:"./lib/mongodb/bson/max_key.js"},
+ {tag:"symbol", path:"./lib/mongodb/bson/symbol.js"},
+ {tag:"timestamp", path:"./lib/mongodb/bson/timestamp.js"},
+ {tag:"long", path:"./lib/mongodb/bson/long.js"},
+ {tag:"bson", path:"./lib/mongodb/bson/bson.js"}
+ ];
+
+// Read all the templates
+var templates2 = [
+ {tag:'index', path:'./dev/tools/doc-templates/index.ejs'},
+ {tag:'index_no_header', path:'./dev/tools/doc-templates/index_no_header.ejs'},
+ {tag:'class', path:'./dev/tools/doc-templates/class.ejs'},
+ {tag:'function', path:'./dev/tools/doc-templates/function.ejs'}
+]
+
+// Extract meta data from source files
+var dataObjects2 = docs.extractLibraryMetaData(apiClasses2);
+// Filter out and prepare the test Objects hash
+var testObjects2 = docs.buildTestHash(docs.extractLibraryMetaData(testClasses));
+// Render all the classes that are decorated
+docs.renderAllTemplates(outputDirectory2, templates, dataObjects2, testObjects2, {index_title:'Binary JSON API'});
+
+// ----------------------------------------------------------------------------
+// PROCESS MARKDOWN DOCUMENTS TO STRUCTURED TEXT
+// ----------------------------------------------------------------------------
+
+// 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:"collections", output:"collections.rst", path:"./docs/collections.md"},
{name:"database", output:"database.rst", path:"./docs/database.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"},
- // {name:"replicaset", output:"replicaset.rst", path:"./docs/replicaset.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"},
+ {name:"replicaset", output:"replicaset.rst", path:"./docs/replicaset.md"},
];
// Tranform the markdown to restructured text
docs.writeMarkDownFile("./docs/sphinx-docs/source/markdown-docs", articles, templates,
View
6 dev/tools/doc-templates/class.ejs
@@ -21,7 +21,7 @@ for(var i = 0; i < entries.length; i++) {
%><%= format("%s\n%s\n%s\n", addLine("=", _name.length), _name, addLine("=", _name.length)) %><%
className = entries[i].ctx.string.replace("()", "");
- %><%= format("\n\n------------------\nConstructor\n------------------\n") %><%
+ %><%= format("\n------------------\nConstructor\n------------------\n") %><%
// Get full description and clean it
var fullDescription = entries[i].description.summary;
@@ -141,7 +141,7 @@ for(var i = 0; i < entries.length; i++) {
// If we have examples render them
if(examples != null && examples[attributeName]) {
- %><%= format("**Examples**\n\n") %><%
+ %><%= format("\n**Examples**\n\n") %><%
var examplesArray = examples[attributeName];
// Iterate over all the examples
for(var ei = 0; ei < examplesArray.length; ei++) {
@@ -260,7 +260,7 @@ for(var i = 0; i < entries.length; i++) {
// If we have examples render them
if(examples != null && examples[examplesName]) {
- %><%= format("**Examples**\n\n") %><%
+ %><%= format("\n**Examples**\n\n") %><%
var examplesArray = examples[examplesName];
// Iterate over all the examples
for(var ei = 0; ei < examplesArray.length; ei++) {
View
11 dev/tools/doc-templates/index_no_header.ejs
@@ -0,0 +1,11 @@
+.. toctree::
+ :maxdepth: 1
+
+<%
+ for(var i = 0; i < entries.length; i++) {
+ // Classname
+ var name = entries[i];
+ // Write out the name
+ %><%= format(" %s\n", name) %><%
+ }
+%>
View
42 docs/database.md
@@ -9,11 +9,11 @@ The first thing to do in order to make queries to the database is to open one. T
db_connector.open(callback);
- * `host` is a server hostname or IP
- * `port` is a MongoDB port, use `mongodb.Connection.DEFAULT_PORT` for default (27017)
- * `server_options` see *Server options*
- * `name` is the databse name that needs to be opened, database will be created automatically if it doesn't yet exist
- * `db_options` see *DB options*
+* `host` is a server hostname or IP
+* `port` is a MongoDB port, use `mongodb.Connection.DEFAULT_PORT` for default (27017)
+* `server_options` see *Server options*
+* `name` is the databse name that needs to be opened, database will be created automatically if it doesn't yet exist
+* `db_options` see *DB options*
## Server options
Several options can be passed to the `Server` constructor with `options` parameter.
@@ -34,16 +34,16 @@ Several options can be set for the `socketOptions`.
Several options can be passed to the `Db` constructor with `options` parameter.
- * `native_parser` - if true, use native BSON parser
- * `strict` - sets *strict mode*, if true then existing collections can't be "recreated" etc.
- * `pk` - custom primary key factory to generate `_id` values (see Custom primary keys).
- * `forceServerObjectId` - generation of objectid is delegated to the mongodb server instead of the driver. default is false
- * `retryMiliSeconds` - specify the number of milliseconds between connection attempts `default:5000`
- * `numberOfRetries` - specify the number of retries for connection attempts `default:3`
- * `reaper` - enable/disable reaper (true/false) `default:false`
- * `reaperInterval` - specify the number of milliseconds between each reaper attempt `default:10000`
- * `reaperTimeout` - specify the number of milliseconds for timing out callbacks that don't return `default:30000`
- * `raw` - driver expects Buffer raw bson document, `default:false`
+* `native_parser` - if true, use native BSON parser
+* `strict` - sets *strict mode*, if true then existing collections can't be "recreated" etc.
+* `pk` - custom primary key factory to generate `_id` values (see Custom primary keys).
+* `forceServerObjectId` - generation of objectid is delegated to the mongodb server instead of the driver. default is false
+* `retryMiliSeconds` - specify the number of milliseconds between connection attempts `default:5000`
+* `numberOfRetries` - specify the number of retries for connection attempts `default:3`
+* `reaper` - enable/disable reaper (true/false) `default:false`
+* `reaperInterval` - specify the number of milliseconds between each reaper attempt `default:10000`
+* `reaperTimeout` - specify the number of milliseconds for timing out callbacks that don't return `default:30000`
+* `raw` - driver expects Buffer raw bson document, `default:false`
## Opening a database
@@ -61,15 +61,15 @@ Resulting database object can be used for creating and selecting [collections](c
### Database properties
- * `databaseName` is the name of the database
- * `serverConfig` includes information about the server (`serverConfig.host', `serverConfig.port` etc.)
- * `state` indicates if the database is connected or not
- * `strict` indicates if *strict mode* is on (true) or off (false, default)
- * `version` indicates the version of the MongoDB database
+* `databaseName` is the name of the database
+* `serverConfig` includes information about the server (`serverConfig.host`, `serverConfig.port` etc.)
+* `state` indicates if the database is connected or not
+* `strict` indicates if *strict mode* is on (true) or off (false, default)
+* `version` indicates the version of the MongoDB database
### Database events
- * `close` to indicate that the connection to the database was closed
+* `close` to indicate that the connection to the database was closed
For example
View
3  docs/insert.md
@@ -16,8 +16,7 @@ Where
* `docs` is a single document object or an array of documents
* `options` is an object of parameters, if you use a callback, set `safe` to true - this way the callback is executed *after* the record is saved to the database, if `safe` is false (default) callback is fired immediately and thus doesn't make much sense.
- * `callback` - callback function to run after the record is inserted. Set `safe` to true in `options` when using callback. First parameter for callback
- is the error object (if an error occured) and the second is an array of records inserted.
+ * `callback` - callback function to run after the record is inserted. Set `safe` to true in `options` when using callback. First parameter for callback is the error object (if an error occured) and the second is an array of records inserted.
For example
View
6 docs/queries.md
@@ -35,8 +35,7 @@ retrieves fields `name` and `title` (and as a default also `_id`) but not any ot
## Find first occurence with findOne()
-`findOne` is a convinence method finding and returning the first match of a query while regular `find` returns a cursor object instead.
-Use it when you expect only one record, for example when querying with `_id` or another unique property.
+`findOne` is a convinence method finding and returning the first match of a query while regular `find` returns a cursor object instead. Use it when you expect only one record, for example when querying with `_id` or another unique property.
collection.findOne([query], callback)
@@ -110,8 +109,7 @@ Whis query matches all records where *key1* is *"value1"* and *key2* is *"value
### OR
-OR queries are a bit trickier but doable with the `$or` operator. Query operator takes an array which includes
-a set of query objects and at least one of these must match a document before it is retrieved
+OR queries are a bit trickier but doable with the `$or` operator. Query operator takes an array which includes a set of query objects and at least one of these must match a document before it is retrieved
{
$or:[
View
33 docs/replicaset.md
@@ -5,9 +5,9 @@ Replicasets
Replica sets is the asynchronous master/slave replication added to Mongodb that takes care off all the failover and recovery for the member nodes. According to the mongodb documentation a replicaset is
- * Two or more nodes that are copies of each other
- * Automatic assignment of a primary(master) node if none is available
- * Drivers that automatically detect the new master and send writes to it
+* Two or more nodes that are copies of each other
+* Automatic assignment of a primary(master) node if none is available
+* Drivers that automatically detect the new master and send writes to it
More information at [Replicasets](http://www.mongodb.org/display/DOCS/Replica+Sets)
@@ -34,13 +34,20 @@ The ReplSetSrvers object has the following parameters
Where
- * `servers` is an array of `Server` objects
- * `options` can contain the following options
- * `rs_name` is the name of the replicaset you configured when you started the server, you can have multiple replicasets running on your servers.
- * `read_secondary` set's the driver to read from secondary servers (slaves) instead of only from the primary(master) server.
- * `socketOptions` - a collection of pr socket settings
- * `timeout` = set seconds before connection times out `default:0`
- * `noDelay` = Disables the Nagle algorithm `default:true`
- * `keepAlive` = Set if keepAlive is used `default:0`, which means no keepAlive, set higher than 0 for keepAlive
- * `encoding` = ['ascii', 'utf8', or 'base64'] `default:null`
-
+* `servers` is an array of `Server` objects
+* `options` can contain the following options
+
+## Replicaset options
+Several options can be passed to the `Replicaset` constructor with `options` parameter.
+
+* `rs_name` is the name of the replicaset you configured when you started the server, you can have multiple replicasets running on your servers.
+* `read_secondary` set's the driver to read from secondary servers (slaves) instead of only from the primary(master) server.
+* `socketOptions` - a collection of pr socket settings
+
+## Socket options
+Several options can be set for the `socketOptions`.
+
+* `timeout` = set seconds before connection times out `default:0`
+* `noDelay` = Disables the Nagle algorithm `default:true`
+* `keepAlive` = Set if keepAlive is used `default:0`, which means no keepAlive, set higher than 0 for keepAlive
+* `encoding` = 'ascii'|'utf8'|'base64' `default:null`
View
1  docs/sphinx-docs/.gitignore
@@ -2,3 +2,4 @@ build/
source/api-generated
source/api-bson-generated
source/api-articles
+source/markdown-docs
Please sign in to comment.
Something went wrong with that request. Please try again.