gitbook-comment
v2.0.1
Published
Generate Markdown file from comments in source code
Downloads
5
Readme
Markdown Generator based on comment (Ideal for Gitbook)
What does it do?
It generate markdown for any comment line starting with ///
(there is a space at the end of it).
/// ### Method Name
/// This is my awesome method.
function Sum(a, b) {
/// This will convert to markdown
// This is a normal comment
return a + b
}
/* Another normal comment */
Above code will become this:
Method Name
This is my awesome method.
function Sum(a, b) {
This will convert to markdown
// This is a normal comment
return a + b
}
/* Another normal comment */
Instruction
- Install the npm using
npm install --save gitbook-comment
- Use
gitbook-comment --help
to read the command line instructions - Edit your package.json with
"scripts": {
"doc-generate": "gitbook-comment generate -p ./",
"doc-clean-up": "gitbook-comment clean-up -p ./",
"doc-publish": "gitbook-comment publish -p ./"
}
- Make suer you have
docs
branch created locally on your machine bygit branch docs
- Make sure you have your code committed on your working branch
- Run
npm run doc-generate
on your working branch:- This will switch branch automatically to
docs
- Create documents next to source files
- Push them to github
- Switch back to working branch
- This will switch branch automatically to
Note If you do not commit your work in working branch, it may get lost in switching the branches.
note: This generator is creating the .md
files in same folder next to the original files.
Alternatively you can generate or clean up docs in any branch
# Generate doc in current branch
npm run doc-generate
# Check help for a command
npm run doc-generate -- -h
# Get full documentation
./node_modules/gitbook-comment/bin/gitbook-comment -h
# Use more more options on a command
npm run doc-generate -- -p ./src -i bin -e js,css,scss
# Clean up generated docs
npm run doc-comment clean-up
If you generate doc manually, make sure they are uploaded to docs or any other none development branch and use gitbook.com integration to view them.
- You can learn more on how it works here
- Demo project is located at https://github.com/pixelsandcode/gitbook-comment-demo