Generating documentaion using Docker.js

Writing code has a part which I think many developers do not focus so much on: .

I for one will not say that documentation is my strongest side as a developer. I do front-end development which involves many technologies like , css, HTML, XSLT and Razor.

Today I discovered a cool project called “Docker”. It seems that it offers automated documentation generation. As most of newer modern apps it is written in javascript using .

Installation – what I did

I am on OS X, and it was relative easy to get started with. There however is a part of Docker which requires Python, that called for som googling but I succeed following these steps:

  • If you dont have Node.js, you need to install node.js.
  • Install docker in node.js: sudo npm install -g docker
  • You need to install Python
  • You need to install pip, which is I guess a sort of package manager for Python.
    sudo easy_install pip
  • You need to install Pygments which, as I understand it will be the part prettifying the code in the generated documentation.
    sudo pip install Pygments

After that you are ready to start generating documentation for your code!

Your first documentation

You now have which will generate a folder containing documentation of the files you specified.

As it is based on node.js you open up a terminal:

I use zsh in my Terminal

You can open terminal simply by pressing Cmd+Space and enter “Terminal” + Enter

From terminal you have access to fire up Node.js. But first navigate to a folder where your source code is. You can use cd “path”.

I use to type “cd ” and then using Finder I find the folder and then drag the folder to the Terminal. That way terminal will paste the path to the folder into the command line.

Like this:

In terminal do a CD to the folder containing your code

We are ready to generate documentation. Docker can take a lot of options, but for now lets just try the basic command, asking it to only document one file.

I have a javascript file (node.js) which is called Fodbold.js, so I will ask Docker to document that:

I fire up docker fodbold.js

By default Docker will create a folder called “Doc”, that you of cause can change using the Docker options.

In my case Docker created this:

Files inside the Doc folder

Now you simply need to open the html file generated, in my case “fodbold.js.html”:

The autogenerated doc from my javascript file

The output – the documentation

As you can see above the documentation is divided into 3 main sections:

  • Navigation
  • Comments to the code
  • The code

It looks pretty nice in my humble opinion, but I did have to do something inside my javascript to get the comments there.

If you run it on your raw code you will not get those comments, and documentation of how to call a function, but wait that part is also easy!

JSDocs in your javascript files

I use Adobe Brackets free editor for coding, and it just happens that there exist (at least) an Extension which can ease the process adding comments to your code.

I use FuncDocr which will prefix your functions through one menu click. You dont see the JSDoc (which FuncDocr adds) in my documentation, as Docker removes them and adds them to the comment section.

Here is an example of the raw JSDoc from my “fodbold.js” file:

A function with JSDoc

The hardest part of documenting

So I guess the hardest part remains to be the actual adding of notes! But no software can help you with that!

The path to a better documentation has been advised here now, so pull yourself together and start documentation.

I for one will try (I promise!) to start doing it.. :–)

Notes

It looks like you can even add Docker to your Grunt scripts.

US

Leave a Reply