nhevia / simple-docs

Simple documentation tool

simple-docs

A simple documentation tool.

Installation

npm install --save-dev @nhevia/simple-docs

Usage

• Add sdoc as a package.json script:

"scripts": {
  "docs": "sdoc"
}

• Use a comment block at the start of any file with sdoc preffix:

/*sdoc
This is the main component
*/

// your code

• Run npm run docs. It will indentify documentation blocks in your project and generates an output file (sdoc.md by default, on root folder):

Since the generated file is markdown, it is supported inside documentation blocks.

/*sdoc
  This is the **main** component
*/

Options

• -f <filename>, --file <filename>
  Set the output file name: sdoc -f docs-components | sdoc --file docs-components

• -ni, --no-index
  Set the output file name. sdoc -ni | sdoc --no-index

Why?

Most major documentation libraries have tools that are beyond the current necessities for personal projects.

I needed a really simple tool to generate documentation for my scripts. Insert a comment block at the beggining of the file describing it and its usage and that's it.

Note that if you're working in a team with multiple people, there are better, more tested and reliable alternatives.

Contributing

Pull requests are more than welcome.

License

Copyright © 2020 Nicolas Hevia This project is MIT licensed

simple-docs's Issues

Resulting file includes an index with hyperlinks to descriptions

Full coverage check

Right now sitting at 72%. Need to add tests for impure functions (fs, fsp).

Accept parameters

• Ignore folders
• Change output file name

Show results after running script

Add tests

Index links point to online repository

Since we know the path of each file (ex: src/sdocs.js) using options to determine git online repository (be github, gitlab, bitbucket, etc) can be reproduced easily (ex: https://github.com/nhevia/simple-docs/blob/master/src/sdocs.js).

File paths in the index are links already (hash links inside the output file), so this needs to be added next to them (icon for example).

Things to take into consideration:

• User is able to opt-out (default: true)
• Git remote option list (github, gitlab, bitbucket, etc). This will need maintenance as providers might differ in their url structure.
• Consider main branch?