docs

Automate repo documentation

🧭 Table of contents

• ✨ Benefits
• 🎒 Requierments
• 🚀 Quickstart
• 📘 Documentation
• 🆘 Troubleshooting
• 🤝 Contributing
• 🧪 Testing
• ⚖️ License

✨ Benefits

• [x] Boilerplates for LICENSE and README
• [x] Customisable
• [x] Simple handlebars template
• [x] Much less overhead than JSDoc
• [x] Leverages data from package.json

🎒 Requierments

To use this package you will need:

• NodeJS

🚀 Quickstart

Setup

In the terminal run:

npm install @danielcobo/docs -D

Note: Don't forget to init your package using npm init first.

In your package.json file add "docs": "docs" to the list of scripts.

  "scripts": {
    "docs": "docs"
  },

Note: In case you're wondering, @danielcobo/ is just a namespace scope - an NPM feature. Scopes make it easier to name modules and improve security.

Usage

Important: running the code below will overwrite existing README.md and LICENSE.md

In the terminal run:

npm run docs

If there are no template files (README.hbs and LICENSE.hbs) boilerplates will be generated to get you started.

Do not edit the .md files directly, instead edit the .hbs templates. After that run npm run docs to regenerate the documentation.

The data passed to templates consists of :

• definition - an array of definitions based on JSDoc style comments in your code
• repo - object consisting of data parsed from package.json

For details see documentation below.

There are also 5 HandlebarsJS helpers you can use:

• noscope
• nogit
• major
• minor
• typecode

| Helper example | Description | | -------------- | ----------- | | {{noscope repo.name}} | returns repository name without the scope. Useful for links, etc. | | {{nogit repo.repository.url}} | returns the git repository url | | {{major repo.version}} | returns major semver version (example: 1) | | {{minor repo.version}} | returns minor semver version (example: 1.0) | | {{{typecode type}}} | returns type names split by \| and with appropriate anchor links. |

Note: replace type with appropriate scoped reference.

You can refer to Handlebars docs regarding the templating syntax.

📘 Documentation

Definition : Object

| Name | Type | Description | | ---- | ---- | ----------- | | description | string | Type/function description text | | name | string | Type/function name | | type | string | Type (i.e. function, method, object...) | | isTypedef | boolean | True if typedef (else assume function) | | param | Array.Param | Function parameters | | property | Array.Property | Type/function properties | | returns | ReturnValue | Function return value | | source | Source | Type/function definition source |

Source: src/parseComments.js:164

ReturnValue : Object

| Name | Type | Description | | ---- | ---- | ----------- | | type | string | Data type of return value | | description | string | Description of return value |

Source: src/parseComments.js:142

Source : Object

| Name | Type | Description | | ---- | ---- | ----------- | | line | number | Source line number | | path | string | Source file path | | url | string | Relative source file url |

Source: src/parseComments.js:134

Property : Object

Type definition property

| Name | Type | Description | | ---- | ---- | ----------- | | name | string | Property name | | type | string | Property value data type | | description | string | Property description | | optional | boolean | True/false if property is optional |

Source: src/parseComments.js:113

Param : Object

Function parameter

| Name | Type | Description | | ---- | ---- | ----------- | | name | string | Parameter name | | type | string | Argument data type | | description | string | Parameter description | | optional | boolean | True/false if parameter is optional | | default | * | Default argument value |

Source: src/parseComments.js:94

Data : Object

| Name | Type | Description | | ---- | ---- | ----------- | | definition | Array.Definition | Definition object | | repo | Package | Object of package.json data |

Source: src/index.js:19

🆘 Troubleshooting

Remember to use run when calling the script.

❌ npm docs will fail.

✅ npm run docs will work.

🤝 Contributing

Anyone can contribute

Contributions come in many shapes and sizes. All are welcome. You can contribute by:

• asking questions
• suggesting features
• sharing this repo with friends
• improving documentation (even fixing typos counts 😉)
• providing tutorials (if you do, please let me know, I would love to read them)
• improving tests
• contributing code (new features, performance boosts, code readability improvements..)

Rules for contributions

General guidelines:

• there are no dumb questions
• be polite and respectful to others
• do good

When coding remember:

• working > maintainability > performance
• best code is no code
• be descriptive when naming
• keep it DRY
• do test

Contribution licence: All contributions are considered to be under same license as this repository.

🧪 Testing

Testing suite: 🃏 Jest | Test command: npm test

Mutation testing suite: 👽 Stryker Mutator | Mutation test command: npm run mutation

If you intend to develop further or contribute code, then please ensure to write and use testing. Strive for 100% code coverage and high mutation scores. Mutation score 100 is great, but it's not always neccessary (if there are valid reasons).

⚖️ License

MIT License