Skip to content

Commit

Permalink
Modifications to markdown docs to work better
Browse files Browse the repository at this point in the history
  • Loading branch information
@christkv
christkv committed Feb 8, 2012
1 parent a0105bb commit 4a83019
Show file tree
Hide file tree
Showing 8 changed files with 138 additions and 122 deletions.
158 changes: 79 additions & 79 deletions dev/tools/build-docs.js
View file
Expand Up @@ -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"}
];

Expand Down Expand Up @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions dev/tools/doc-templates/class.ejs
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -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++) {
Expand Down Expand Up @@ -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++) {
Expand Down
11 changes: 11 additions & 0 deletions dev/tools/doc-templates/index_no_header.ejs
View file
@@ -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) %><%
}
%>
42 changes: 21 additions & 21 deletions docs/database.md
View file
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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

Expand Down
3 changes: 1 addition & 2 deletions docs/insert.md
View file
Expand Up @@ -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

Expand Down
6 changes: 2 additions & 4 deletions docs/queries.md
View file
Expand Up @@ -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)

Expand Down Expand Up @@ -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:[
Expand Down
33 changes: 20 additions & 13 deletions docs/replicaset.md
View file
Expand Up @@ -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)

Expand All @@ -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`
1 change: 1 addition & 0 deletions docs/sphinx-docs/.gitignore
View file
Expand Up @@ -2,3 +2,4 @@ build/
source/api-generated
source/api-bson-generated
source/api-articles
source/markdown-docs

0 comments on commit 4a83019

Please sign in to comment.