Support for generating an "index" file.

[mikefowler]

After generating my documentation in the, for example, docs/ directory, I would like to be able to hit http://localhost/docs/index.html and get a listing of all the files that have been documented. Docco generates the handy "jump to" menu, but that is only handy once you're on a single file's page.

Is this something you're interested in for this project, @DavidSouther? Would be happy to contribute code or test.

[DavidSouther]

This is Github, just send a PR ;)

Yeah, that's totes fine. To my knowledge, Docco doesn't generate that, so my preferred approach would be to consume some (fictitious) "docco-index" project, that handles the index.html generation, then calling that from the grunt-docco task. If it matched the docco API, it would be awesomely easy for a user to decide which they wanted via their package deps, and grunt-docco would handle the rest on the fly.

[neocotic]

This doesn't really sound like something this Grunt task should do. Not only because adding and "index page" should really be part of the Docco project, but also because it's very common for developers to actually have files named index and they may very well want to generate documentation for them as well.

I'm not sure if you were looking for this task to start a server for the documentation too, but I'd recommend using the grunt-contrib-connect plugin in conjunction with this one for this purpose, much like the grunt-contrib-qunit plugin suggests.

Edit: Apologies, I clicked the Close button by accident.

[DavidSouther]

In the meantime, just visiting file://path/to/project/docs/ will give you an "index" of the generated docco files.

[DavidSouther]

@neocotic Looks like we stepped over eachother on comments :) Agreed, generating the index file in the grunt task is not appropriate. If there were another library to handle that, then grunt-docco could load the "right" one at runtime, giving the dev team full control if they wanted such an index file.

[neocotic]

@DavidSouther Agreed. It would be nice to switch between them if a specific option is specified and keeping it separate from this project is perfect to keep this task as simple as possible.

I know the main Docco project won't implement this due to the reason I specified earlier, but there's no reason someone else can't fork it and attempt to add this, provided that fork is kept up-to-date.

Edit: I had this tab open all day and when I finally get around to commenting it, you'd replied just a minute before :smile:

[DavidSouther]

@mikefowler There's our answer! I think it would be great to have "docco-index", it'd be nice to see that merged into docco itself, but grunt-docco would be happy to use it if it existed.

[mikefowler]

@DavidSouther, @neocotic: exactly the reason why I wanted to raise the issue here first! Thanks for having the discussion.

@neocotic: agreed, this fictitious “docco-index” would have to special-case the index file if there was already a source file named index.

I certainly recognize that it's possible to hit the file:// URL and get a listing, but it seems logical that this "index" we're talking of should exist anyways.

[fibo]

I just create an index.js referencing the files, sine I need it also for the node require. btw it would useful