@danielcobo/docs

Automate repo documentation

Usage no npm install needed!

<script type="module">
  import danielcoboDocs from 'https://cdn.skypack.dev/@danielcobo/docs';
</script>

README

docs

Automate repo documentation

๐Ÿงญ Table of contents

โœจ Benefits

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

๐ŸŽ’ Requierments

To use this package you will need:

๐Ÿš€ 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