unbroken-doc v0.3.0
Background
Writing doc is one of the headaches in many projects. Some pains include, but not limited to:
- No good way to refer to a specific part of content
Links are vulnerable due to code refactoring
This plugin is to provide a way to easily create stable markers across your project, and make your documentation links more strong.
Installation
First, you need to have node/npm and gulp.
cd MY_PROJECT
npm install unbroken-doc
npm install gulp
And then, in your gulpfile.js
, you should specify the tasks.
There are two in this plugin at the moment:
- doc
- validate
Therefore, you could have something like this:
var gulp = require('gulp');
var unbrokenDoc = require('unbroken-doc');
unbrokenDoc.init('my-custom-project', OPTIONS);
gulp.task('doc', unbrokenDoc.tasks.doc);
gulp.task('validate', unbrokenDoc.tasks.validate);
// which defines the tasks as below
# gulp doc
# gulp validate
How to use in your project
After having the gulp task ready, you can cd
to your project folder, and run gulp doc
(or the task that you defined).
The process will keep watching your project, and help you parsing markers.
Add a marker
At anywhere on your project, you would simply enter something like @@{ SOME DESCRIPTION }
on any place of any text file.
The watcher will detect it and replace it with something like:
@{{
@[ SOME DESCRIPTION ]{_projectkey_randomkey}
}}@
Note that, if you insert the @@{}
pre-marker on a file of a special type, e.g. on a js file,
the actual marker will also be enclosed within a multi-line comment automatically.
/*@{{
@[ ]{_projectkey_randomkey}
}}@*/
Add a reference to a marker
That's so easy, simply copy the bit @[ SOME DESCRIPTION ]{_projectkey_randomkey}
to anywhere that
you want to have the reference.
In most editor (IDE), you can simply move your cursor at the line of the marker, and press ctrl+c
or cmd+c
, this line will then be copied to your clipboard.
And next, you just simply paste it to the place you'd like to have the reference.
Config details
unbrokenDoc.init( projectKey, options )
projectKey
is the most important information in the setting, it will determine how your marker is generated.
For more information about options
see below.
Options of config
OPTIONS is the config object, if nothing is passed into .init()
, the default object is used.
You can refer to the default config object below to get more idea:
{
// the comment syntax, so that the marker can be error-free embeded on the content
commentSyntax: {
none: {start: '', end: ''},
xml: {start: '<!--', end: '-->'},
java: {start: '/*', end: '*/'}
},
// the file that we going to process, the comment gives the comment syntax to be used in such file type
fileTypes: {
sh: {},
py: {},
sql: {
comment: 'java'
},
java: {
comment: 'java'
},
js: {
comment: 'java'
},
json: {
comment: 'java'
},
less: {
comment: 'java'
},
css: {
comment: 'java'
},
jsp: {
comment: 'xml'
},
html: {
comment: 'xml'
},
xml: {
comment: 'xml'
},
mustache: {},
data: {},
properties: {},
md: {
comment: 'none'
},
txt: {
comment: 'none'
}
},
// the src path to watch
srcPath: '.',
// where the cache file sits
docCacheFolderPath: './.doc_cache/',
// which files that we ignore. Follows are the default ignores
ignores: [
// ignore all folders that start with '.'
/[\/\\]\./,
/^\../,
// ignore node_modules, bower_modules, vendor, build folders
/([\/\\]|^)node_modules[\/\\]/,
/([\/\\]|^)bower_modules[\/\\]/,
/([\/\\]|^)vendor[\/\\]/,
/([\/\\]|^)build[\/\\]/,
// ignore typical non-text files
/\.(mp4|avi|mkv|rm|rmvb|mp3|wav|xls|doc|xlsx|docx|class|png|jpg|gif|rar|eot|svg|ttf|woff|woff2|swf|db|jar|iml|jpeg)$/i,
],
// you can simply specify the following ignore rule, so that they are appended to the main ignore
addIgnores: [
]
};
Or, you can pass in a function as the config
in .init(projectKey, config)
.
The function will have the current config as input, and should return the new config object.
unbrokenDoc.setup('my-project', function(config) {
config.srcPath = './src';
return config;
});
The processing logic of this plugin in Chinese :
@ 程序运作逻辑 {unbroken_doc_385f148fa}