Unable to use the doc tool

[tciuro]

I've tried to use the doc tool to generate a sample using the README example:

## module

    Stability: 3 - Stable

description and examples.

### module.property

* Type

description of the property.

### module.someFunction(x, y, [z=100])

* `x` {String} the description of the string
* `y` {Boolean} Should I stay or should I go?
* `z` {Number} How many zebras to bring.

A description of the function.

### Event: 'blerg'

* Argument: SomeClass object.

Modules don't usually raise events on themselves.  `cluster` is the
only exception.

## Class: SomeClass

description of the class.

### Class Method: SomeClass.classMethod(anArg)

* `anArg` {Object}  Just an argument
  * `field` {String} anArg can have this field.
  * `field2` {Boolean}  Another field.  Default: `false`.
* Return: {Boolean} `true` if it worked.

Description of the method for humans.

### someClass.nextSibling()

* Return: {SomeClass object | null}  The next someClass in line.

### someClass.someProperty

* String

The indication of what someProperty is.

### Event: 'grelb'

* `isBlerg` {Boolean}

This event is emitted on instances of SomeClass, not on the module itself.

I have saved to test.markdown. Thepackage.son` file contains the following reference:

"bin": "./generate.js"

So I tried the following:

cd ~/Downloads/io.js-1.x/tools/doc
./generate.js ~/Desktop/test.markdown

I get the following:

➜  doc  ./generate.js /Users/tito/Desktop/test.markdown 
./generate.js: line 1: //: is a directory
./generate.js: line 3: syntax error near unexpected token `('
./generate.js: line 3: `var processIncludes = require('./preprocess.js');'

Invoking it via node doesn't get better results:

node generate.js /Users/tito/Desktop/test.markdown 

Results in:

➜  doc  node generate.js /Users/tito/Desktop/test.markdown 
Input file = /Users/tito/Desktop/test.markdown
undefined

/Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:48
        if (er) throw er;
                      ^
Error: Inappropriate heading level
{"type":"heading","depth":2,"text":"module"}
    at /Users/tito/Downloads/io.js-1.x/tools/doc/json.js:34:19
    at Array.forEach (native)
    at doJSON (/Users/tito/Downloads/io.js-1.x/tools/doc/json.js:15:9)
    at next (/Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:46:27)
    at /Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:14:5
    at processIncludes (/Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:24:33)
    at preprocess (/Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:11:3)
    at /Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:36:3
    at fs.js:272:14
    at Object.oncomplete (fs.js:108:15)

How is the doc tool suppose to work?

[indutny]

cc @chrisdickinson @isaacs

[chrisdickinson]

I think the problem is that you have ## module at the start, and it's expecting # module.

[tciuro]

Hm... that doesn't fix it. The extra # is just markdown. The sample I'm using was taken from doc's README file:

https://github.com/iojs/io.js/tree/v1.x/tools/doc

[oskwazir]

With an appropriate header I can get the example to work. I added # Foo to the first line of the example posted in the README and the generator worked fine for me. Without the first header I got the following error

Error: Inappropriate heading level
{"type":"heading","depth":2,"text":"module"}

[tciuro]

@TheWazir I have added # Foo to the first line like you state and it still doesn't work. I'm calling it like so:

node generate.js ~/Desktop/test.markdown

This is the error I get:

➜  doc  node generate.js ~/Desktop/test.markdown
Input file = /Users/tito/Desktop/test.markdown
undefined

/Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:48
        if (er) throw er;
                      ^
Error: Inappropriate heading level
{"type":"heading","depth":3,"text":"module.property"}
    at /Users/tito/Downloads/io.js-1.x/tools/doc/json.js:34:19
    at Array.forEach (native)
    at doJSON (/Users/tito/Downloads/io.js-1.x/tools/doc/json.js:15:9)
    at next (/Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:46:27)
    at /Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:14:5
    at processIncludes (/Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:24:33)
    at preprocess (/Users/tito/Downloads/io.js-1.x/tools/doc/preprocess.js:11:3)
    at /Users/tito/Downloads/io.js-1.x/tools/doc/generate.js:36:3
    at fs.js:272:14
    at Object.oncomplete (fs.js:108:15)

How are you invoking the tool?

[oskwazir]

I used the following and they both worked node generate.js example.md and node generate.js ~/Downloads/example.md.

[tciuro]

@TheWazir this is so weird. Would you mind emailing me the example.md file? There's got to be something I'm missing, though I copied the text verbatim, as far as I can tell!

[tciuro]

@TheWazir was kind enough to send me a copy of his file. Still, I saw the same problems. So I decided to clone the project and voilà! It doesn't fail like before. There seems to be a problem with the ZIP version.

However, I now see JSON output on terminal but no generated html file anywhere. Is the JSON output supposed to be fed to some other tool?

[Fishrock123]

@tciuro please let us know / re-open if you are still having issues. :)

[tciuro]

@Fishrock123 as I mentioned in my last comment, I see some output in the terminal, but nothing else. How is this tool supposed to work?