Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/opuscapita/sequelize-to-markdown
DEPRECATED Create Markdown documentations out of sequelize models.
https://github.com/opuscapita/sequelize-to-markdown
andariel bnp library tool util
Last synced: 2 months ago
JSON representation
DEPRECATED Create Markdown documentations out of sequelize models.
- Host: GitHub
- URL: https://github.com/opuscapita/sequelize-to-markdown
- Owner: OpusCapita
- License: mit
- Created: 2017-03-14T11:50:20.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2022-11-14T15:27:40.000Z (about 2 years ago)
- Last Synced: 2024-10-27T22:38:50.131Z (2 months ago)
- Topics: andariel, bnp, library, tool, util
- Language: JavaScript
- Homepage:
- Size: 139 KB
- Stars: 1
- Watchers: 17
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sequelize-to-markdown
[](https://coveralls.io/github/OpusCapita/sequelize-to-markdown?branch=master)
Sequelize to Markdown is a simple tool to document the data structure of [sequelize](https://www.npmjs.com/package/sequelize) models. Its output is template based to enable developers to change the output structure, style or even the output type e.g. by creating html [templates](#templating).
This module provides a comfortable APIs and a full featured command line client.
# WARNING
Please, do NOT use it. This module has several importain issues:
- Markdown is meant to be manually edited, not auto-generated - you should NOT push markdown to wiki automatically
- This module is very outdated - if you are still using it for whatever you should think again
- This module has messy dependencies and sqlite3 is used for tests but is marked as dependency - and it is not that simple to install it on newer node images
- No one is maitaining this repository for years
### Install
```
npm install -g sequelize-to-markdown
```
##### Requirements
This module works by including code. That means, that your model files get required like common modules. To enable sequelize-to-markdown to correctly load your models, each file included by this tool has to either provide a default function call or an init() method.
```JS
module.exports = function(db, config) { ... }
- or -
module.exports.init = function(db, config) { ... }
```
To get your models documented, you will have to provide a small amount of doc comments in your code. To start a minimal setup, you only have to provide the **@class** or **@lends** (or @memberof) tags from [JSDoc](http://usejsdoc.org/). If you add text to your class and field definitions, it will be used as descriptions in the output.
```JS
const DataTypes = require('sequelize');
/**
* Class description.
* @class MyUser
*/
sequelize.define('MyUser',
/** @lends MyUser */
{
/** Test comment. */
id : {
type : DataTypes.INTEGER(),
allowNull : false,
primayKey : true,
autoIncrement : true
},
/** Test name comment. */
name : {
type : DataTypes.STRING(128),
allowNull : false
}
});
```
### Command-line interface
After installing and having your code ready, you may use the command-line interface (CLI) on the terminal of your computer. The command is named "sq2md".
```
sq2md --help
Usage: sq2md [options] [path]
Options:
-h, --help output usage information
-r, --recursive Scan recursively.
-t, --template Template file to use for output generation.
-o, --output-type Where to put the output. Possible values: stdout, file, file-per-class, file-per-src.
-f, --output-file File to output results to if output type is file.
-p, --output-path Path to output results to if output type is file-per-class or file-per-src.
-c, --config Path to a JSON config file to use.
--init Initialization function to be called for every source file.
--init-config JSON config to be passed to an init function.
--output-ext File extension of result files if output type is file-per-class or file-per-src.
--field-bl [,] List of fields to ignore.
--dir-filter RegExp for filtering directories when looking for source files.
--file-filter RegExp for filtering files when looking for models.
--path-bl [,] List of paths to ignore.
--sq-config JSON config to be passed to sequelize.
```
#### Config file
The config file represents all configuration options available to run the tool from command line. These are almost the same options as shown in the [DefaultConfig](#defaultconfig) section of the API description. In order to use the module programmatically, you will have to use the [DefaultConfig](#defaultconfig) settings instead.
```JS
{
"fieldBlacklist": [],
"models": {
"paths": [],
"pathBlacklist": [],
"recursive": false,
"initFunction": null,
"initConfig": {},
"directoryFiler": "[^\\/\\.*]",
"fileFilter": "\\.js$"
},
"input": {
"templateFile": "templates/default.njk"
},
"output": {
"type": "StdOut",
"file": {
"splitting": "AllInOne",
"path": null,
"extension": ".md"
}
},
"sequelize": {}
}
```
### API
You might also want to use the API of this tool as a library. The library provides two methods to call. A parse() and a render() method.
The **parse()** method returns an object containing all information extracted from the source.
The **render()** method does the same but outputs a processed template depending on the input and output settings of the passed configuration object.
```JS
const sq2md = require('sequelize-to-markdown');
var resultObj = sq2md.parse({ models : { paths : [ '...' ] } });
var resultStr = sq2md.render({ models : { paths : [ '...' ] } });
console.log(resultObj);
console.log(resultStr);
```
For configuration options please have a look at the [DefaultConfig](#defaultconfig) section.
#### Templating
This module uses [Nunjucks](https://www.npmjs.com/package/nunjucks) in order to structure the parsed sequelize models. By changing the provided or creating a new template, you would be able to create almost every formatted text output.
#### DefaultConfig
```JS
{
fieldBlacklist : [ ],
models : {
paths : [ ],
pathBlacklist : [ ],
recursive : false,
initFunction : null,
initConfig : { },
directoryFiler : new RegExp('[^\/\.*]'),
fileFilter : new RegExp('\.js$')
},
input : {
templateFile : 'templates/default.njk'
},
output : {
type : this.OutputType.ReturnOnly,
file : {
splitting : this.FileSplitting.AllInOne,
path : null,
extension : '.md'
},
contentFilter : item => item.replace(/\n{3,}/g, "\n\n")
},
sequelize : {
}
}
```