Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Man #478

Merged
merged 6 commits into from

1 participant

Anatoliy Chakkaev
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 20, 2013
  1. Added doc builder

    authored
  2. Route compound help to man

    authored
  3. Added some docs

    authored
  4. Indent sources

    authored
  5. Amend man structure

    authored
This page is out of date. Refresh to see the latest.
1  .gitignore
View
@@ -10,3 +10,4 @@ log/test.log
analyse-ab.r
log
tags.sh
+man
53 Makefile
View
@@ -1,14 +1,55 @@
+# TESTS
+
+TESTER = ./node_modules/.bin/mocha
+OPTS = --require ./test/init.js
+TESTS = test/*.test.js
+
test:
- @./node_modules/.bin/mocha --require ./test/init.js test/*.test.js
+ $(TESTER) $(OPTS) $(TESTS)
test-verbose:
- @./node_modules/.bin/mocha --reporter spec --require ./test/init.js test/*.test.js
+ $(TESTER) $(OPTS) --reporter spec $(TESTS)
testing:
- ./node_modules/.bin/mocha --watch --reporter min --require ./test/init.js --require should test/*.test.js
+ $(TESTER) $(OPTS) --watch $(TESTS)
+
+# MAN DOCS
+
+CLI_MAN = $(shell find docs/cli -name '*.md' \
+ |sed 's|.md|.1|g' \
+ |sed 's|docs/cli/|man/|g' )
+
+API_MAN = $(shell find docs/api -name '*.md' \
+ |sed 's|.md|.3|g' \
+ |sed 's|docs/api/|man/|g' )
+
+API_WEB = $(shell find docs/api -name '*.md' \
+ |sed 's|.md|.html|g' \
+ |sed 's|docs/api/|man/html/|g' )
+
+man/%.1: docs/cli/%.md scripts/doc.sh
+ @[ -d man ] || mkdir man
+ scripts/doc.sh $< $@
+
+man/%.3: docs/api/%.md scripts/doc.sh
+ @[ -d man ] || mkdir man
+ scripts/doc.sh $< $@
+
+man/html/%.html: docs/api/%.md scripts/doc.sh
+ @[ -d man/html ] || mkdir -p man/html
+ scripts/doc.sh $< $@
+
+MAN = $(API_MAN) $(CLI_MAN)
+
+build: all
+
+all: $(MAN) $(API_WEB)
+
+man: $(MAN)
+
+# WEBSITE DOCS
+
docs:
node docs/sources/build
apidocs:
makedoc lib/*.js lib/*/*.js -t "RailwayJS API docs" -g "1602/express-on-railway" --assets
-.PHONY: test
-.PHONY: doc
-.PHONY: docs
+.PHONY: test doc docs
19 bin/compound.js
View
@@ -46,12 +46,17 @@ process.nextTick(function () {
break;
}
}
+ var topic = args.shift();
+ if (topic) {
+ showMan(topic);
+ return;
+ }
var help = [
'Usage: compound command [argument(s)]\n',
'Commands:'
];
var commands = [
- ['h', 'help', 'Display usage information'],
+ ['h', 'help [topic]', 'Display compound man page'],
['i', 'init', 'Initialize compound app'],
['g', 'generate [smth]', 'Generate something awesome']
];
@@ -102,4 +107,16 @@ process.nextTick(function () {
});
+function showMan(topic) {
+ var manDir = require('path').resolve(__dirname + '/../man/man3');
+ require('child_process').spawn(
+ 'man', [manDir + '/' + topic + '.3'],
+ {
+ customFds: [0, 1, 2],
+ env: process.env,
+ cwd: process.cwd()
+ }
+ );
+}
+
/*vim ft:javascript*/
74 docs/api/helpers.md
View
@@ -0,0 +1,74 @@
+compound-helpers(3) - view helpers
+==================================
+
+## DESCRIPTION
+
+Helpers produce html code. [Built-in][BUILT-IN HELPERS] helpers available in any
+view. Custom helpers available in specific controller, see [CUSTOM HELPERS][]
+section.
+
+## BUILT-IN HELPERS
+
+### stylesheetLinkTag(file1[, file2[, ...[, fileN]]])
+
+Generates `<link rel="stylesheets" href="..." />` tag.
+Following ejs:
+
+ <%- stylesheetLinkTag('reset', 'style', 'mobile') %>
+
+will produce in develompent env:
+
+ <link rel="stylesheet" type="text/css" href="/stylesheets/reset.css" />
+ <link rel="stylesheet" type="text/css" href="/stylesheets/style.css" />
+ <link rel="stylesheet" type="text/css" href="/stylesheets/mobile.css" />
+
+and in production env:
+
+ <link rel="stylesheet" type="text/css" href="/stylesheets/cache/somehash.css" />
+
+depending on `app.set('merge stylesheets');` option.
+
+### javascriptIncludeTag
+### linkTo
+### contentFor
+### anchor
+### matcher
+### icon
+### imageTag
+### csrfTag
+### csrfMetaTag
+### metaTag
+### formFor
+### fieldsFor
+### errorMessagesFor
+### formTag
+### formTagBegin
+### formTagEnd
+### labelTag
+### submitTag
+### buttonTag
+### selectTag
+### optionTag
+
+## FORM HELPERS
+
+### begin
+### end
+### label
+### select
+### input
+### file
+### textarea
+### checkbox
+### submit
+
+## CUSTOM HELPERS
+
+There are two kind of custom helpers: application-wide and local. To define
+custom helpers create *./app/helpers/application_helper.js* file. Local helpers
+available only for specific controller, and should be located in
+*./app/helpers/controllerName_helper.js* file.
+
+## SEE ALSO
+
+routing(3)
2  docs/api/index.txt
View
@@ -0,0 +1,2 @@
+# manuals
+routing(3) routing
338 docs/api/routing.md
View
@@ -0,0 +1,338 @@
+compound-routing(3) - compound map drawer
+=========================================
+
+## DESCRIPTION
+
+The purpose of routes is to connect an URL with a controller action.
+
+## FILE
+
+`config/routes.js` should export `routes(map)` function:
+
+ exports.routes = function draw(map) {
+ map.root('dashboard#home');
+ map.namespace('admin', function(admin) {
+ admin.resources('users');
+ });
+ };
+
+## EVENT
+
+You can use `routes` event on compound object to define routes:
+
+ compound.on('routes', function(map, compound) {
+ map.get('auth', 'session#auth');
+ });
+
+It could be useful when you want to define some routes before application
+initialization. When app initialized use `compound.map` object.
+
+## BASIC ROUTING METHODS
+
+To define routes we have map object which have number of methods:
+
+* `get`:
+ Define route for GET method.
+
+* `post`:
+ Define route for POST method.
+
+* `put`:
+ Define route for PUT method.
+
+* `del`:
+ Define route for DELETE method.
+
+* `all`:
+ Define route for all http methods.
+
+All these methods have following signature:
+
+ map.get(path, handler, middleware, options);
+
+Params meaning:
+
+* `path`:
+ some path, which could contain params, see [ROUTE PATH PARAMS][]
+
+* `handler`:
+ string `controllerName#actionName`
+
+* `middleware`:
+ function or array of functions (optional)
+
+* `options`:
+ object containing params for route (optional), see [ROUTE OPTIONS][]
+
+## ADVANCED ROUTING METHODS
+
+### NAMESPACE
+
+### RESOURCE
+
+## ROUTE PATH PARAMS
+
+TODO
+
+## ROUTE OPTIONS
+
+TODO
+
+## EXAMPLES
+
+To link `GET /signup` with `new` action of `users` controller:
+
+`map.get('signup', 'users#new');`
+
+The following route will link `GET /` to the `index` action of the`home` controller:
+
+`map.root('home#index');`
+
+## URL HELPERS
+
+URL helpers provide you convenient way to work with paths in your app. When you
+define route:
+
+ map.get('bunny', 'bunny#show');
+
+you can use `pathTo.bunny` in your controllers and views, which will generate
+
+ /bunny
+
+path for you. You also can specify another helper name is you want using `as`
+param:
+
+ map.get('bunny', 'bunny#show', {as: 'rabbit'});
+
+and now `pathTo.rabbit` available.
+
+If your route has param, for example
+
+ map.get('profile/:user', 'users#show');
+ map.get('posts/:post_id/comments/:comment_id', 'comments#show');
+
+URL helper will accept parameter (String), so that:
+
+ pathTo.profile('Bugs_Bunny', 'users#show');
+ > '/profile/Bugs_Bunny'
+ pathTo.post_comment(2, 2383);
+ > '/posts/2/comments/2383'
+
+<p>
+<strong>Why use URL helpers?</strong><br/>
+First of all it's convenient and beauty. But what is more important
+url helpers take care about namespaces. In case if your application will be
+used as part of another application, mounted on some URL like "/foreign-app"
+URL helpers will return correct value: "/foreign-app/profile/Bugs_Bunny"
+instead of "/profile/Bugs_Bunny"
+</p>
+
+How to learn what helper name was generated? Read "Debugging" section.
+
+## Debugging
+
+To debug routes of your compound application you can use `compound routes`
+command (or shortcut `compound r`). You can also specify optional argument for
+filtering by helper name or method, for example:
+
+ ~: ) compound r post
+ posts GET /posts.:format? posts#index
+ posts POST /posts.:format? posts#create
+ new_post GET /posts/new.:format? posts#new
+ edit_post GET /posts/:id/edit.:format? posts#edit
+ post DELETE /posts/:id.:format? posts#destroy
+ post PUT /posts/:id.:format? posts#update
+ post GET /posts/:id.:format? posts#show
+ ~: ) compound r GET
+ posts GET /posts.:format? posts#index
+ new_post GET /posts/new.:format? posts#new
+ edit_post GET /posts/:id/edit.:format? posts#edit
+ post GET /posts/:id.:format? posts#show
+ ~: ) compound r new
+ new_post GET /posts/new.:format? posts#new
+
+## Resources
+
+Resource-based routing provides standard mapping between HTTP verbs and controller actions:
+
+ map.resources('posts');
+
+will provide the following routes:
+
+ helper | method | path | controller#action
+ posts GET /posts posts#index
+ posts POST /posts posts#create
+ new_post GET /posts/new posts#new
+ edit_post GET /posts/:id/edit posts#edit
+ post DELETE /posts/:id posts#destroy
+ post PUT /posts/:id posts#update
+ post GET /posts/:id posts#show.
+
+To list all available routes you can run the command `compound routes`.
+
+The first column of the table represents the `helper` - you can use this identifier in views and controllers to get the route. Some examples:
+
+```
+path_to.new_post # /posts/new
+path_to.edit_post(1) # /posts/1/edit
+path_to.edit_post(post) # /posts/1/edit (in this example post = {id: 1})
+path_to.posts # /posts
+path_to.post(post) # /posts/1.
+
+```
+
+### Options
+
+If you want to override default routes behaviour, you can use two options: `as` and `path` to specify a helper name and a path you want to have in the result.
+
+<strong>
+{ as: 'helperName' }
+</strong>
+
+Path helper aliasing:
+
+ map.resources('posts', { as: 'articles' });
+
+This will create the following routes:
+
+ articles GET /posts.:format? posts#index
+ articles POST /posts.:format? posts#create
+ new_article GET /posts/new.:format? posts#new
+ edit_article GET /posts/:id/edit.:format? posts#edit
+ article DELETE /posts/:id.:format? posts#destroy
+ article PUT /posts/:id.:format? posts#update
+ article GET /posts/:id.:format? posts#show.
+
+<strong>
+{ path: 'alternatePath' }
+</strong>
+
+If you want to change the base path:
+
+ map.resources('posts', { path: 'articles' });
+
+This will create the following routes:
+
+ posts GET /articles.:format? posts#index
+ posts POST /articles.:format? posts#create
+ new_post GET /articles/new.:format? posts#new
+ edit_post GET /articles/:id/edit.:format? posts#edit
+ post DELETE /articles/:id.:format? posts#destroy
+ post PUT /articles/:id.:format? posts#update
+ post GET /articles/:id.:format? posts#show
+
+<strong>
+Both "as" and "path" together
+</strong>
+
+If you want to alias both the helper and the path:
+
+ map.resources('posts', { path: 'articles', as: 'stories' });
+
+This will create the following routes:
+
+ stories GET /articles.:format? posts#index
+ stories POST /articles.:format? posts#create
+ new_story GET /articles/new.:format? posts#new
+ edit_story GET /articles/:id/edit.:format? posts#edit
+ story DELETE /articles/:id.:format? posts#destroy
+ story PUT /articles/:id.:format? posts#update
+ story GET /articles/:id.:format? posts#show
+
+## Nested resources
+
+Some resources may have nested sub-resources, for example `Post` has many `Comments`, and of course we want to get a post's comments using `GET /post/1/comments`.
+
+Let's describe the route for our nested resource:
+
+ map.resources('post', function (post) {
+ post.resources('comments');
+ });.
+
+This routing map will provide the following routes:
+
+ $ compound routes
+ post_comments GET /posts/:post_id/comments comments#index
+ post_comments POST /posts/:post_id/comments comments#create
+ new_post_comment GET /posts/:post_id/comments/new comments#new
+ edit_post_comment GET /posts/:post_id/comments/:id/edit comments#edit
+ post_comment DELETE /posts/:post_id/comments/:id comments#destroy
+ post_comment PUT /posts/:post_id/comments/:id comments#update
+ post_comment GET /posts/:post_id/comments/:id comments#show
+ posts GET /posts posts#index
+ posts POST /posts posts#create
+ new_post GET /posts/new posts#new
+ edit_post GET /posts/:id/edit posts#edit
+ post DELETE /posts/:id posts#destroy
+ post PUT /posts/:id posts#update
+ post GET /posts/:id posts#show.
+
+### Using url helpers for nested routes
+
+To use routes like `post_comments` you should call helper with param: parent resource or identifier before nested resource:
+
+ path_to.post_comments(post) # /posts/1/comments
+ path_to.edit_post_comment(post, comment) # /posts/1/comments/10/edit
+ path_to.edit_post_comment(2, 300) # /posts/2/comments/300/edit
+
+## Namespaces
+
+You may wish to organize groups of controllers under a namespace. The most common use-case is an administration area. All controllers within the `admin` namespace should be located inside the `app/controllers/` directory.
+
+For example, let's create an admin namespace:
+
+ map.namespace('admin', function (admin) {
+ admin.resources('users');
+ });
+
+This routing rule will match with `/admin/users`, `/admin/users/new` and will create appropriate url helpers:
+
+ admin_users GET /admin/users.:format? admin/users#index
+ admin_users POST /admin/users.:format? admin/users#create
+ new_admin_user GET /admin/users/new.:format? admin/users#new
+ edit_admin_user GET /admin/users/:id/edit.:format? admin/users#edit
+ admin_user DELETE /admin/users/:id.:format? admin/users#destroy
+ admin_user PUT /admin/users/:id.:format? admin/users#update
+ admin_user GET /admin/users/:id.:format? admin/users#show
+
+## Restricting routes
+
+If you need routes only for several actions (e.g. `index`, `show`), you can specify the `only` option:
+
+ map.resources('users', { only: ['index', 'show'] });
+
+If you want to have all routes except a specific route, you can specify the `except` option:
+
+ map.resources('users', { except: ['create', 'destroy'] });
+
+## Custom actions in resourceful routes
+
+If you need some specific action to be added to your resource-based route, use this example:
+
+ map.resource('users', function (user) {
+ user.get('avatar', 'users#avatar'); // /users/:user_id/avatar
+ user.get('top', 'users#top', {collection: true}); // /users/top
+ });
+
+## Middleware
+
+You may want to use middleware in routes. It's not recommended, but if you need
+it you can put it as second argument:
+
+ map.get('/admin', authenticate, 'admin#index');
+ map.get('/protected/resource', [ middleware1, middleware2 ], 'resource#access');
+
+## Subdomain
+
+**experimental**
+
+If you want to support subdomain filter, specify it as `subdomain` option:
+
+ map.get('/url', 'ctl#action', {subdomain: 'subdomain.tld'});
+
+use \* as wildcard domain
+
+ map.get('/url', 'ctl#action', {subdomain: '*.example.com'});
+
+This feature relies on `host` header, if your node process behind nginx or proxy,
+make sure you've passed this header to process.
39 docs/cli/compound.md
View
@@ -0,0 +1,39 @@
+compound(1) -- MVC framework for NodeJS
+=======================================
+
+## SYNOPSIS
+
+ compound <command> [args] [opts]
+
+## DESCRIPTION
+
+Compound is MVC framework for the Node JavaScript platform. It adds structure
+and API to ExpressJS application, provides tools and generators for rapid
+web applications development.
+
+Run `compound help [topic]` to get help on specific topic.
+
+## BUGS
+
+When you find issues, please report them:
+
+* web:
+ <http://github.com/1602/compound/issues>
+* email:
+ <compoundjs@googlegroups.com>
+
+## HISTORY
+
+See compound-changelog(1)
+
+## AUTHOR
+
+* [Anatoliy Chakkaev](http://anatoliy.in/)
+* [1602](https://github.com/1602/)
+* [anatoliychakkaev](https://github.com/anatoliychakkaev/)
+* [@1602](http://twitter.com/1602)
+* <mail@anatoliy.in>
+
+## SEE ALSO
+
+compound(3)
9 package.json
View
@@ -3,6 +3,7 @@
"version": "1.1.5-18",
"author": "Anatoliy Chakkaev",
"contributors": [
+ "Anatoliy Chakkaev <mail@anatoliy.in> (http://anatoliy.in)",
"Sascha Gehlich <contact@filshmedia.net> (http://filshmedia.net)"
],
"description": "CompoundJS - MVC framework for NodeJS",
@@ -23,6 +24,11 @@
"compound": "bin/compound.js",
"rw": "bin/compound.js"
},
+ "man": [
+ "./man/compound.1",
+ "./man/helpers.3",
+ "./man/routing.3"
+ ],
"dependencies": {
"yaml-js": ">= 0.0.2",
"coffee-script": ">= 1.1.1",
@@ -46,6 +52,7 @@
"mocha": "1.8.1"
},
"scripts": {
- "test": "make test"
+ "test": "make test",
+ "prepublish": "make build"
}
}
21 scripts/doc.sh
View
@@ -0,0 +1,21 @@
+#!/bin/bash
+
+src=$1
+dest=$2
+
+mkdir -p $(dirname $dest)
+
+case $dest in
+ *.[13])
+ ronn --roff $1 --pipe --organization=1602\ Software --manual=CompoundJS > $2
+ exit $?
+ ;;
+
+ *.html)
+ ronn -5 $1 --pipe\
+ --style=toc\
+ --organization=1602\ Software\
+ --manual=CompoundJS > $2
+ exit $?
+ ;;
+esac
Something went wrong with that request. Please try again.