Support for recursive dirs

[nevir]

You can generate docs that mirror your directory structure by calling docco dir/. The standard behavior of docco some.file or docco dir/* is preserved, to avoid breaking current users (if you had a dir in the list of sources, 0.3.0 blows up).

This hopefully satisfies #38. Also, it is hopefully a more straightforward way than --structured-output in #45 (Since most of the usage out there seems to be about generating docs along side a src/ or lib/ dir, rather than inside it).

[bruth]

+1

[nevir]

Example output: http://nevir.github.com/node-autorequire/autorequire.html (mostly of note are the style changes to the jump menu)

[Raynos]

+1

[nevir]

Thanks for the catch @Raynos! Pushed w/ that in

Also, tweaked the output of the jump list a bit, and regenerated my example docs w/ it: http://nevir.github.com/node-autorequire/autorequire.html It is much easier to visually parse, particularly for deep directory structures

It's probably worth deduping the directory headers - that's a larger change, though.

[Raynos]

Whilst your at it. If you could fix the the jump to box so it has a scrollbar in if you generate a linked docco with many (>100) files

[jswartwood]

@nevir

Initially I was looking to accomplish a recursive docco, however I chose --structured-output to make my initial pull more direct. In many cases your naive recursion may prove unusable (e.g. a developer outputs compiled js into the same dir as the coffee source). In my case: I currently exec("find . -name *.js | grep -E \"\\/\\w+\\.war\\/\" | grep -v -E \"\\/build\\/|\\/\\.svn\\/|\\/min\\/\"", ... (with different greps depending on flags) in a node wrapper command.

Also, (many of my current node scripts have this same flaw) a dependence on find means that Docco loses Windows compatibility. Because of these issues, I have simply deferred the recursion to a Cakefile or Bash wrapper script. If we want to seriously consider recursive documentation, I suggest we add a flag syntax for pattern exclusion/inclusion (e.g. find or grep). If you have interest on a collaboration here, I'm all for it.

I do really like your adjustments to the jump menu for a recursive structure; it looks great. Unfortunately some of our projects would still be too big for a fixed element to handle reasonably, so I am still weighing other design options. I've opened a new issue (#53), and would love feedback or help.

[nevir]

@jswartwood - yeah, totally agree. I was just aiming for the 80% case; most of the examples of docco usage seem to segregate source and compiled source/docs. (piping a bunch of commands together gets old quickly, and docco is all about being quick and dirty!)

I'm honestly not all that sold on how I accomplish the recursive docs (it's far heaver than yours) - but I do want a super simple way to generate recursive docs, to get people up and running quickly.

Yeah, let's figure out a way to get these patches working together

[krisnye]

Is this going to get pulled into docco, or do we need a forked documentation generator that can handle recursive directories?

[vorg]

+1

[knarf-se]

+313373

[jswartwood]

@nevir I was thinking about the proposed merge that you had suggested, but I don't know if I really want to keep recursive lookups in docco. I have been pondering a few things:

• Should docco take care of this (as you have done)?
• Should docco also handle watching files?
• Should all of this be done in a Cakefile (or similar)?

I started working on a recursive branch with the intention of possibly adding watching as well, but quickly realized this started to break the philosophy of quick and dirty... I was making docco too smart. So came to the conclusion that I just need to spend some time finishing another project that I had started a while back.

Anyway to get to the point...
I pushed up my temporary work with recursive searching (#45 (comment)). If you have a chance to check it out, I'd like to get your opinion.

[knarf-se]

@jswartwood: Hehe, maybe you (or I, or someone else) should make docco even more stupid (^»^)

This should probably go in it's own branch or something, but it would be good if one could pass docco a file and just receive an array of HTML-fragments -- then one could do whatever they want with that.

I'm quite happy with docco as is, right now. Except for two or three things, it ain't recursive and it ain't processing multiline comments in JS (I run it over the express framework, hoping to get better docs). It also blarbs my code that I have commented out for one or another reason. (°_°)

Right now, I'm going to re-install my laptop. And while I do that, I'll continue to write my own yet-another-webframework-solution, but I'll probably start working on docco in the small. Hmm, what the heck! I'll just include a fork of it as an submodule! ☺

[mbrevoort]

+1

[jswartwood]

@knarf-se You may want to check out https://github.com/visionmedia/dox It used to be similar in purpose to docco, but now seems to have turned toward the fragment/data approach.

[knarf-se]

@jswartwood: Thank you very much! Right now this recursive docco quite much covers my needs, but when my project becomes more complicated, things like call-graphs and dependency-graphs would be nice. But I'll add that to my remember-URL-textfile :D

You does not happen to know a program that can help those who have fragmented memory? ;)

[mbrevoort]

Hey all, I decided to just fork Docco and start to build out a project documentation generator that also looks at a project's README.md, package.json and recursively walks source. It also uses CLOC to generate some highlevel stats. Let me know what you think... https://github.com/mbrevoort/docco-husky

[ghost]

Why isn't this merged yet? It's a feature we all want.

[ghost]

@mbrevoort: Just tried your fork and generated the whole project's documentation. Amazing work!

Won't use Docco til it supports that kind of generation.

[nevir]

@johnnywengluu This pull request doesn't quite fit the spirit of docco (quick and dirty) - a lot of that discussion occurred over on #45.

I've been playing with building a more complex doc generator, I'd be curious if it better fits the needs for your project: http://nevir.github.com/groc

[ghost]

So Docco is not for projects but for a few files in a flat directory structure?

I feel it wouldn't help as many people with projects they wanna documentate.

Good library, thanks for recommendation. I'll try it out and see if it helps. I'll get back to you.

[nevir]

@johnnywengluu Yeah, that seems to be the rough delineation for docco's support.

Supporting deep directory structures comes with a good amount of baggage (as I found when writing this patch and groc). Different projects have different needs for the generated structure, and it's hard to get right or even have sane defaults. That deviates very heavily from the quick 'n dirty principles of docco.

[ghost]

@nevir If you could provide options like docco-husky so I could choose what folders/files I want to documentate that would be flexible enough to solve all the different folder structures I believe.

[ndnichols]

@nevir groc has solved all my docco issues (and looks better, to boot.) Thanks.