jbt / docker Goto Github PK

The version listed in package.json is about 10 months old and still uses the old path.exists API. I'd recommend bumping to the newest 2.3.3. See https://github.com/bevry/watchr/blob/master/History.md

BTW, love this expansion on docco, great work!

Too much escaping.

Hi,

I have some problem with the Markdown syntax and the CoffeeScript comments syntax.

When I have something like that:

###
## My Title
###

It will generate a H2 tag correctly rendered but when I do something like this:

###
### My Title
###

I have a syntax error in my editor and the generation of the doc is not possible.

In this tool: https://npmjs.org/package/coffeedoc They address the problem by offering the possibility to escape the # comments like that \#\#\#. As the author said, it is ugly but it works and should be a workaround.

Or maybe there is already a solution that I missed?

Currently, the output has white-space: pre on the code output, which causes ridiculous horizontal scrolling for long code lines.

I propose to change this to pre-wrap in a future release, probably 0.2.1 or 0.2.2 depending on what other features take priority.

With 0.2.0's support for custom CSS files, this can easily be reverted, but I think pre-wrap would be a better default. If anyone feels sufficiently strongly about this to actually be watching this issue, speak now or forever hold your peace.

Long comments don't line up with the code they're talking about, due to the vertical-align rule on line 229 of _base.sass:

td.code
  padding: 8px 15px 8px 25px
  width: 100%
  vertical-align: bottom
  border-left: 1px solid

Changing vertical-align to top makes things look much cleaner.

I am pointing docker at a source repository with 20 - 30 files. Watchr does not seem to be picking up changes very well. Only about 30% of my file saves cause docker to re-execute.

On OSX 10.7, using Docker master as of today, and using [email protected]

Swapped out Docco for this on a project I'll be open sourcing soon. Love it. Has a few flaws/bugs, but overall generates excellent output. May report some issues/fix a couple as time permits. Cheers from the SF Bay!

Not really an issue and more of a feature request.

Would it be possible to augment the Docker.prototype.languageParams function to do shebang lookup ?

The way I do it as of now (i do not code in JS very much as of now sorry), is running docker on a snapshot of a repository of code after renaming filenames with an extension, based on a shell pipe, the gist of which is :

for i in $(cat testshebang | grep "^#\!" | sed  -e "s/^\#\!\s*\(\/usr\/bin\/env\)\?\(.*\)/\2/"  ); do  echo $(basename $i); done

testshebang

#!/usr/bin/env python
#! /usr/bin/env  clj
#!/bin/sh
#! /usr/bin/zsh
#!/usr/bin/foo/bar/perl
#!   /usr/bin/foo/bar/perl
#  !/donotmatchme
some code
some code

outputs

python
clj
sh
zsh
perl
perl

Anyway, awesome fork.
Thx for your work !

Would be nice to be able to use the same documentation like on .coffee files.

Hi,

first of all, thanks a lot for the very nice port of Docco!

I was wondering if there is an easy way of setting the treeVisible variable always to TRUE (or FALSE), instead of using the localStorage.

I am referring to this line in the doc-script.js file:

var treeVisible = (window.localStorage && window.localStorage.docker_showTree == 'yes');

Thanks,
shakty

The main Docco project now supports Literate CoffeeScript which is a perfect fit for such a project.

Would be a really nice addition to Docker.

Hi, first of all thanks for making what I was looking for :)

But your description states docker parses jsDoc as well, but this is not the case...any idea?

I'd rather this not be enabled by default as it could confuse things, but it'd definitely be good to have a command-line flag to include all files regardless of whether they're properly supported.

Would need some kind of filetype blacklist or sanity check to ensure we're not trying to include binary files or images (though on that note support for images could be interesting)

Looks like it gets confused by anything other than the ones it explicitly understands

I keep getting this error:

Assertion failed: (!uv__io_active(&stream->io_watcher, UV__POLLOUT) || !ngx_queue_empty(&stream->write_completed_queue) || !ngx_queue_empty(&stream->write_queue) || stream->shutdown_req != NULL || stream->connect_req != NULL), function uv_read_stop, file ../deps/uv/src/unix/stream.c, line 1329.

Do you have any idea what it is related to? Thanks.

Hello, I try to use docker on a coffeescript project and I am not able to make it working correctly.

I use this command:

docker my_file.coffee -n --extras fileSearch,goToLine -c friendly

The problem is that the ### comments (multiline or not) are not parsed correctly. The parsing show this kind of lines as a sort of Markdown and therefore I have a result where some comments like the following will be partially parsed. A part is correctly parsed and appears in the documentation and the rest appears as code (the jsdoc comments especially).

###
## My title that appears correctly

my text comment that appears in the documentation correctly

@param {Object} p1 My first parameter that not appears correctly
@param {Object} p2 My second parameter that not appears correctly
@return {Object} The function return that not appears correctly too
###

Am I doing something wrong in the docker usage ?

Showdown isn't maintained and the GFM parts are just my own hacks. marked is properly maintained. Use that instead.

Hi, I have found an issue where a line ending with a colon gets parsed as a heading, which screws up the docs:

/**
 * ## This should be a real heading
 *
 * And this line should not:
 * - because it's just a title to a list
 * - and it should not be indexed as a heading
 */

Hi,

I have a new issue when I want to write a Markdown code block which contains HTML.

For example, I have this code block (without spaces for the block comments caracters):

` ` `
<ul>
  <li><a href="...">...</a></li>
  ...
</ul>
` ` `

It will render something like that:

• ...
...

I tried to do something like this:

` ` `
<ul>
...
` ` `

And the rendering was the same as Github shown.

Am I doing something wrong ? I also tried to specify the language like that ````html` without success.

With the -w flag, whenever a file gets processed it overwrites the folder tree.

It would be pretty neat if there was a way to provide a style sheet to allow the creation of custom schemes.

How about running docker per file?, like so

$docker -i example.js -o docs

HI again,

Just a quick question to understand why the behavior of comments is not the same for line and block comments.

If I write something like that:

###
My line of description

@param {String} paramName And the parameter description
@return {Object} And the return description
###

The JSDoc like is generated in the documentation as expected, but if I write that:

# My line of description
#
# @param {String} paramName And the parameter description
# @return {Object} And the return description

The doc generated is a simple documentation without the JSDoc for @param and @return

Is it a restriction of Docker or other restriction?

I've only used this in CoffeeScript so far, but I noticed that JSDoc tags aren't formatted if there's any white space in the same line before them.

I would like to be able to hook into code-block text before it gets syntax highlighted. This is similar to #59 but technically very different, I think.

I hacked docker.js to replace the module names in my define and require calls with links to the proper file. I find it super useful, but I had to add code in several (seemingly) arbitrary places to make it work.

It's not ready to bring in, but I could get what I wrote on a fork if someone wanted to check it out and try to write something better.

Links in markdown can go to other files. To make it work in docker i have to link to other file.md.html but for GitHub I have to use otherfile.md

It would be nice if we may link to the file (works in GitHub) and docker will add the .html automatically while saving the document.

As an alternative to pygments. Has many languages.

http://atom.github.io/highlights/

Open file / watch limits are sometimes being problematic. Using whatever's built into node core would presumably be better than using a module. Problem then is compatibility. Can't remember when fs.watch was added to node core but it'll definitely mean dropping support for 0.4 (ok I guess) and probably 0.6 as well if docker is to rely on it. Needs further investigation.

Related: #40

Probably will have to wait until #31 as Pygments doesn't have a LESS lexer

It's still not obvious enough when pygments fails because pygments isn't installed. Should be easy enough to add in a nice message saying "oops, looks like you don't have pygments". Would need to check Windows compatibility though.

Highlighting with Pygments gets confused as the comment delimiter is always plonked in at 0-spaced indentation, which breaks the whitespace-dependent SASS syntax, and Pygments thinks anything from then-on is a comment. This will need to be thought through more thoroughly.

Also, /* can be used to indicate a single-line comment, so the multi-line parsing needs to be rethought slightly to take this into account.

Hi again,

Just a quick remark for improvement (in my opinion)

When I write that:

###!
My comments or code in progress or anything else that should not appear in the doc
!###

I get the same result in the code side. I expected to have the block comment generated without the ! in the final result.

For sure it is not so important and only my preference. Maybe this could be an option or something like that in a future version?

Fails with the following output:

events.js:72
        throw er; // Unhandled 'error' event
              ^
Error: spawn ENOENT
    at errnoException (child_process.js:948:11)
    at Process.ChildProcess._handle.onexit (child_process.js:739:34)

Need to do an lstat on each file to check that it won't break everything.

UPDATE: problem is with symlinks with dead targets. Need to do a sanity check to make sure files exist before trying to read them

Hi,

I am trying to write something like that:

@param {Function, String} template The template to register

The documentation generated gives that:

 String} Function template The template to register

If I write that (remove the comma after the Function):

@param {Function,String} template The template to register

I get this result:

 template Function String The template to register 

In my opinion, we should be able to write spaces inside the {} as they act as delimiters.

Hi,
this issue is about a feature request. Dunno if u r interested in implemented, or if it is feasible at all with the current codebase.

I would like to define custom tags. In fact, some of my functions are emitting events, and I would like to have a tag @emit where I list all the events that can be generated by the function.

I am pretty sure this would be an important feature, and I would not be the only one interested.

Thanks for the great software!

Things that look like HTML tags disappear from the output because they get rendered as part of the DOM.

For a reasonably sane example:

/**
 * ## My Function
 * Description
 * @return {Promise<String>}
 */

The <String> part disappears whereas I would expect it to be output as text.

This is the same regardless of whether it is in a title, description, tag name, tag type, tag description etc.
Not sure if it should be escaped for anything other than the tag type, but this sort of formatting is reasonably common I think.

Some nice work has been done on the mainstream docco recently, which among other things involves dropping the confusing pygments dependency. In light of this, I think it'd be good to kill off all dependencies not resolvable by npm.

I want to generate a documentation for my node.js express application. But unfortunatly it doesnt include files like css or jade template files. Is there a way to include them in the generated documentation?

If i have e.g. a file test.coffee with the content

###
  Example:
  ```js
  if (true) {
      x = 42;
  }
  ```
###

and run

$ docker test.coffee

i get the following output with a lost indent:

if (true) {
x = 42;
}

I found a workaround by adding a * before lines which have an indent.
Is there a better way?

I am using docker 0.2.10 and pygments 1.4.

I'm just trying out docker for the first time, but I keep getting this exception no matter what I try. I just upgraded to node 0.10, maybe it's not compatible?

events.js:72
throw er; // Unhandled 'error' event
^
Error: spawn ENOENT
at errnoException (child_process.js:945:11)
at Process.ChildProcess._handle.onexit (child_process.js:736:34)

Example that will error (the @static is the line that causes the issue):

/**
* # This is the header
*
* Description goes here.
*
* @static
* @param foo Something to foobar.
*/
function test(foobar) {
    console.log(foobar);
}

Resulting error:

/usr/local/lib/node_modules/docker/src/docker.js:726
          if(bits[0].charAt(0) == '{') tag.types = grabType(bits).split(/ *[|,
                     ^
TypeError: Cannot call method 'charAt' of undefined

When jumping to a file from the search tool, the file location is not expanded in the left-side browser. That's a annoying if we want to see the context of the file, that is, it's folder, other included files, etc. especially on huge projects.

Plus, would be nice to see the current opened file highlighted in the browser.

What do you think?

Ran into this error message today

<project path>/node_modules/docker/src/docker.js:265
          for(var i = 0; i < list.length; i += 1){
                                 ^
TypeError: Cannot read property 'length' of undefined
    at <project path>/node_modules/docker/src/docker.js:265:34
    at Object.oncomplete (fs.js:297:15)

After a little digging it seems that the error being thrown in fs.readdir is ignored, and list is left undefined. I added a console.error(err) and turns out I was running into the EMFILE error because my ulimit was too low (the default for OS X is only 256, yikes). I bumped it up and everything is working. I've run into this before with other Node.js programs and I've found a few reasonable solutions:

1. Throw the error so people can Google it and realize what the problem is and how to fix it.
2. Use a queue to only open one file at a time (could be pretty slow).
3. Use a queue and a reasonable concurrency limit like async has.

Anyway, love the tool, great work!

simply including that string (e.g. in @charset "UTF-8";) seems to result in a parsing error, with output like

"//----{DIVIDER}----"

in the docs...

When Docco generated files are viewed at a small enough viewport (appears to be 320px), the file will layout the code in a single column format where the comment block will appear on top. See here for an example.

It be nice if the source container could mimic this behavior as well.

Hi I hope you can help as this is exactly what I've been searching for for ages.

(My system is windows7 64 bit)

I have been unable to install using 'npm install docker -g' it fails every time saying that scripts/install.sh is not recognised as an internal or external command.

I was able to install it manual from the gitHub and it does work but only if there is not a sub directory within the specified -i directory. If there is a sub directory it generates all the js.html files in the root and then stops.

I put a trace in at docker.js line 159 and saw that it is reading my folder structure and identifying all the contents but not generating all the files.
In the example I have a folder called src and a subfolder called utils.

(output from cmd):
C:\Users\macguffin\Desktop\New folder (3)>docker -i src
./
example.js
IwgIncludes.js
MGoldMain.js
utils
utils\MakeCash.js
utils\MS.js
Generated: \example.js.html
Generated: \IwgIncludes.js.html
Generated: \monopolyGoldMain.js.html

I also put a trace in at line 195 to see the bits and noticed that it had a double \ is this correct? I wondered if maybe the windows file system was messing with you regex?

utils
utils\MakeCash.js -trace from line 159 - filename
[ 'utils\MakeCash.js' ] - trace from line 195 - bits
utils\MS.js -trace from line 159 - filename
[ 'utils\MS.js' ] - trace from line 195 - bits

Cheers

when parsing the headings, docker doesn't seem to dasherize the titles which leads to anchor tags containing whitespace.

Is there a reason that the multiline support for SASS/SCSS is commented out?

On this line, there are only inline comment options. I've changed this to use the same commenting format as Javascript, and added JSDoc without any noticeable issues. The JSDoc processing is useful for mixins.

I've only tested this for SCSS.

Suggested Update:

  scss: {
    extensions: [ 'scss' ],
    comment: '//', multiLine: [ /\/\*\*?/, /\*\// ], jsDoc: true
  },

When rendering the file name var in the head script, more filtering is needed on Windows platforms. The backslash path separator is operating as the start of an escape sequence when file and/or directory names start with a "u", so the backslash also needs to be escaped.

For example, if my file name is:

c:\home\github\stitches\src\js\util\util.js

It is rendered as:

'c:\home\github\stitches\src\js\util\util.js'

Instead of:

'c:\\home\\github\\stitches\\src\\js\\util\\util.js'

Which causes a syntax error in JavaScript. I imagine the change should be made in the Docker.prototype.renderCodeHtml method. I came up with this, but you may want to be more thorough:

filename = filename.replace(this.inDir,'').replace(/^[\/\\]/,'');
if (pathSeparator === "\\") {
  filename = filename.replace(/\\/g, '\\\\');
}

Very nice tool, by the way. I actually posted a question about this exact thing way back in 2011 - http://stackoverflow.com/questions/7128721/docco-like-tool-that-accommodates-jsdoc-style-comments