Gutendocs NPM | npm.io

GutenDocs

Named for Johannes Gutenberg, the inventor of movable type, GutenDocs is CLI dev tool that auto-generates API Documentation from your javascript code base by parsing JSDoc comments from your .js and .jsx files.

Team

Product Owner: Uday Trivedi
Scrum Master: Peter Gierke
Development Team Members: Yuqi Zhu, David Park

This product is currently in development. We would love any feedback from anyone making use of GutenDocs while it is under development. Email us at gutentechdevs@gmail.com.

Brief overview

JSDoc is a widely accepted markup language standard for annotating javascript code. An example of what a JSDoc comment looks like is below:

/**
 * Finds the next unused name in the directory to save a backup file
 * @param { string } location the path to the directory of intesting
 * @param { string } baseName the original name of the file being backed up
 * @example findValidBackupName('somePath', exam.js) returns exam.backup.js
 * @example findValidBackupName('somePath', exam.js) returns exam.backup0.js
 * @example findValidBackupName('somePath', exam.js) returns exam.backup1.js
 * @return { string } a string taking the form of a unused backup name
 */
const findValidBackupName = (location, baseName) => {...}

GutenDocs will parse each JSDoc comment in your code base like this:

All of the comments will be put together into an webpage that can be viewed like in the image below:

Usage

Getting ready to use GutenDocs

From anywhere call npm install -g gutendocs. This will give you access to the gutendocs shell command.

Initializing gutendocs

Now from any location, preferably the root of a repo, you can call gutendocs init [foldername] which will initialize an API folder directly in the directory you are currently working in. It will also create a settings file called .gutenrc.json and a .gutenignore that will allow you to customize your usage of GutenDocs.

.gutenrc explanation

.gutenrc.json is a file that contains all the settings you can customize for for your API Documentation. An explanation of those settings is below:

designSettings.js explanation

designSettings.js is a file that allows you to manage the design of the API Documentation. It will be generated with defaults in your API folder.

Using themes

At GutenTech we know style is important. We have set up some default themes that you can quickly use to adjust the way your API is rendered. You can see a list of the themes and their descriptions with gutendocs theme --list or gutendocs theme -l. You can then set the theme of your choice by calling gutendocs theme [themeName]. You can add custom themes in the API Documentation theme folder following the existing structure to add your own.

Using your .gutenignore

Your .gutenignore works just like a .gitignore file and will ignore folders and files you specify and allow for the use of * as a wild card. You can also place nested .gutenignore files inside of subfolders and it will add ignore criteria in that folder and its subfolder as indicated in that directories .gutenignore. .gutenignore is generated for you with the node_modules folder, any files or folders starting with a . and the generated API Documentation folder will be ignored from the start. You most likely will want to add other folders to this such as test folders, mock folders or anything else that you might not want or need included in the API Documentation.

Adding your JSDoc string documented information to the API Documentation.

Now that you have configured gutendocs settings and your styles the way you want it, is time to extract all those well written comments from your code and organize them into a beautiful document. Go to whatever folder or file you want to generate an API Documentation for and run either gutendocs parse [filename] to parse a single file or gutendocs parse --all to parse the current directory and any subdirectories

Depending on your verbosity level (which can be set with gutendocs verbosity/verbose [0-5]) you will then see an output with information about the parsing process. If you want to know more, like which files have not been parsed, or why they were not parsed, then turn up the verbosity.

Viewing your API Documentation

Now that you have set all your settings like you wanted, and parsed the files you wanted, lets open up your API Documentation.

Now you can open the index.html file inside your API Documentation folder in your web browser of choice, et voila. Your API Documentation has been created for you. Congratulations!

Trouble Shooting/FAQ

Help! I've forgotten how to use gutendocs! No worries, just run `gutendocs help` or `gutendocs <command> --help` for more information.

Help! I've made a mess of my API Documentation folder. And I am missing files or don't know what it should look like. No worries, If you want to start from scratch you can call `gutendocs reset` to overwrite your whole folder to be the way it was when you initialized. If you want to retain a copy of the way it was before you can run `gutendocs reset --backup` and it will back up a copy of your current version of the folder as [foldername].backup.

Help! I've made a mess of my .gutenrc.json and it's missing things I need or is now invalid. No worries, If your gutenrc.json is an invalid JSON object and you try to run any gutendoc's commands it will ask you if you would like to restore the .gutenrc.json to its original state. If you choose to do that it will also ask if you want to save a backup file. The backup will be saved in the same location as the .gutenrc.json as .gutenrc.backup.json so you can use it as a reference while you are rebuilding on the newly created gutenrc.json.

Help! I just want to start over from scratch. No worries. Just delete your .gutenrc, .gutenignore and the API Documentation folder and rerun `gutendocs init`.

Help! I deleted a ton of settings in gutenrc.json. No worries. For any setting not present in gutenrc.json the defaults will be loaded.

Help! I've found a problem that I don't know what to do with that isn't covered above! Sorry to hear that. Please send an email to gutentechdevs@gmail.com and we will look into this issue for you.