Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/be-fe/unbroken-doc


https://github.com/be-fe/unbroken-doc

Last synced: about 14 hours ago
JSON representation

Awesome Lists containing this project

README 

        
[中文文档请看这里](./README_cn.md)



# 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: ''},

        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_}