jashkenas / docco Goto Github PK

If you have a multi-line string literal that interpolates, and you include a #{foo} in on a single line, docco thinks it's a comment. (In fact, this is true of any line that starts with a #) This I think is because the regex is not context-sensitive to string terminators. Seems like a tricky thing to fix, since you probably need to get a AST to determine if the line is part of a multi-line string or not.

npm ERR! Error parsing json /usr/local/lib/node/.npm/docco/0.3.0/package/package.json
npm ERR! parse error  SyntaxError: Unexpected token }
npm ERR! parse error      at Object.parse (native)
npm ERR! parse error      at /usr/local/lib/node/.npm/npm/0.3.17/package/lib/utils/read-json.js:71:17
npm ERR! parse error      at P (/usr/local/lib/node/.npm/npm/0.3.17/package/lib/utils/read-json.js:62:40)
npm ERR! parse error      at cb (/usr/local/lib/node/.npm/npm/0.3.17/package/lib/utils/graceful-fs.js:31:9)
npm ERR! parse error      at [object Object]. (fs.js:86:5)
npm ERR! parse error      at [object Object].emit (events.js:39:17)
npm ERR! parse error      at afterRead (fs.js:843:12)

Here's the culprit:

"bin": {
    "docco":      "./bin/docco",
  }

Trailing comma! (really shouldn't matter, but it's not official JSON)

If I use a single @ in CoffeeScript files, I get a red border around it.

<span class="err">@</span>

Why does it get a err class? While @set works fine?

<span class="nx">@set</span>

It seems I found the place on the Pygments repo on this line: https://bitbucket.org/birkenfeld/pygments-main/src/cf58553e620a/pygments/lexers/web.py#cl-1665

(r'@?[$a-zA-Z_][a-zA-Z0-9_]*', Name.Other, 'slashstartsregex')

Does anyone know how to submit a change to their repo or what the right regex should look like?

This is related to issue #111

The Problem

One thing people often prefer to customize, when working with code, is the syntax highlighting color scheme. Docco currently has no support for user customized highlighting colors, outside of modifying the main docco.css file.

It would be nice to see support for a user specified command line switch that could reference a set of named color themes, which would be CSS snippets that just customize the syntax highlighter specific styles.

I believe a concise solution could be conceived of, but I'm not entirely convinced it's a worthwhile feature to pursue. Interest in this feature can be gauged by the discussion here.

Possible Implementation

We could take the current syntax highlighting styles out of docco.css, and put them in a file, say :

 resources/syntax.default.css

Then user customized styles could be replacements of that default file, for example:

 resources/syntax.lasers.css

The highlighting file could then be appended to the specified CSS file when docco is run, to produce the same single-file css output as it currently does.

A command line (switch -s?) could then be added in which the name of the syntax highlighting color scheme could be specified, e.g.

 docco -s lasers src/docco.coffee

would produce a CSS output that is a concatenation of the specified CSS theme, and resources/syntax.lasers.css.

When I zoom to the full width of the screen, the type is blurry. I am not an expert:” Is this a typeface issue? Can it be fixed in the default css?

npm ERR! couldn't read package.json in /tmp/npm-1298082734115/1298082736953-0.2839640537276864/contents/package
npm ERR! Error installing [email protected]
npm ERR! Error: Failed to parse json
npm ERR! Unexpected token }
npm ERR! {
npm ERR! "name": "docco",
npm ERR! "description": "The Quick and Dirty Literate Programming Documentation Generator",
npm ERR! "keywords": ["documentation", "docs", "generator", "coffeescript"],
npm ERR! "author": "Jeremy Ashkenas",
npm ERR! "version": "0.3.0",
npm ERR! "licenses": [{
npm ERR! "type": "MIT",
npm ERR! "url": "http://opensource.org/licenses/mit-license.php"
npm ERR! }],
npm ERR! "engines": {
npm ERR! "node": ">=0.2.0"
npm ERR! },
npm ERR! "directories": {
npm ERR! "lib" : "./lib"
npm ERR! },
npm ERR! "main" : "./lib/docco",
npm ERR! "bin": {
npm ERR! "docco": "./bin/docco",
npm ERR! }
npm ERR! }

The correct JSON formatting seems to be:

{
"name": "docco",
"description": "The Quick and Dirty Literate Programming Documentation Generator",
"keywords": [
"documentation",
"docs",
"generator",
"coffeescript"
],
"author": "Jeremy Ashkenas",
"version": "0.3.0",
"licenses": [
{
"type": "MIT",
"url": "http://opensource.org/licenses/mit-license.php"
}
],
"engines": {
"node": ">=0.2.0"
},
"directories": {
"lib" : "./lib",
"main" : "./lib/docco",
"bin": {
"docco": "./bin/docco",

  } 

}
}

I tried to use docco. It requires pygments. I have a problem with pygments installation, then I just typed pygments in my ubuntu console and it suggests me to run sudo apt-get install python-pygments. After that I made what I want - created documentation for coffee file. So, what I'm writing about: maybe it would be useful to add this hint for ubuntu users, I mean:

"To install Docco, first make sure you have Node.js, Pygments (install the latest dev version of Pygments from its Mercurial repo or in ubuntu: sudo apt-get install python-pygments), and CoffeeScript. Then, with NPM:"

With source code in multiple languages, docco always ends up splitting on the first languages splitter.

This may not sound like a big deal to some, but to those of us that care about the design of our source code, it’s horrid. A large part of the point of docco and other literate-code documentation generators is to put the code in front of your user; and when I put a lot of work into ensuring the code is beautiful for said user, I want to ensure that that work translates into my docco-generated webpages.

Compare the following screenshots; notice the loss of alignment below the var keyword in the emboldened version:

This is an issue in all browsers known to me.

My suggestion is to modify the default docco.css design to call attention to code elements without applying emboldening.

When I run cake doc, a bug happens:
Error: Command failed: sed: can't read s/docco.css/resources/docco.css/: No such file or directory
at ChildProcess. (/usr/lib/node/libraries/sys.js:227:15)
at node.js:756:9

The problem is caused by two apostrophes in send invocation in the Cakefile. I'm by no means a sed guru, but for me just dropping those apostrophes altogether seems to fix the issue.

Just an idea I tried.. I figured this could be useful to someone else besides me, esp those who do alot of mathematical programming

Mathjax supplies a javascript library on a CDN, and when you insert Latex into your HTML code, the formulas get rendered properly on the page. Combined with docco, this could make an amazing tool for annotating mathematical, or highly algorithmic code.

When I add this line of HTML to my resources/docco.jst template head, I can just insert Latex directly into my code comments, and the formulas show up perfectly in the generated HTML

-------------------------- HTML to go into HEAD tag -------------------------------------
script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML-full"

/script

---------------------------- END HTML -----------------------------------------------------------------------------

It would be great to have an option when using docco, to include the MathJax javascript libraries into the docco.jst template.
You might not want to place it in the template by default, but perhaps a command line option or something?

docco *.js

Could not use Pygments to highlight the source.

node -v
0.8.8

A possibility for improving generation speed, could be to change sync routines to their async alternatives.

I might attempt a patch depending if you want to give it a shot first :D

I used easy_install Pygments==dev in order to try to get prevent the boxes being added to the @ symbols in my CoffeeScript code. While the HTML still generates successfully, Docco outputs a node buffer:

docco src/batman.coffee                                                                                                                                                                                                                   
<Buffer 2f 55 73 65 72 73 2f 4e 69 63 6b 2f 41 70 70 6c 69 63 61 74 69 6f 6e 73 2f 70 79 67 6d 65 6e 74 73 2f 70 79 67 6d 65 6e 74 73 2f 70 6c 75 67 69 6e 2e 70 79 3a 33 39 3a 20 55 73 65 72 57 61 72 6e 69 6e 67 3a 20 4d 6f 64 75 6c 65 20 70 79 67 6d 65 6e 74 73 20 77 61 73 20 61 6c 72 65 61 64 79 20 69 6d 70 6f 72 74 65 64 20 66 72 6f 6d 20 2f 55 73 65 72 73 2f 4e 69 63 6b 2f 41 70 70 6c 69 63 61 74 69 6f 6e 73 2f 70 79 67 6d 65 6e 74 73 2f 70 79 67 6d 65 6e 74 73 2f 5f 5f 69 6e 69 74 5f 5f 2e 70 79 63 2c 20 62 75 74 20 2f 75 73 72 2f 6c 6f 63 61 6c 2f 6c 69 62 2f 70 79 74 68 6f 6e 32 2e 37 2f 73 69 74 65 2d 70 61 63 6b 61 67 65 73 2f 50 79 67 6d 65 6e 74 73 2d 31 2e 34 64 65 76 5f 32 30 31 31 30 38 32 35 2d 70 79 32 2e 37 2e 65 67 67 20 69 73 20 62 65 69 6e 67 20 61 64 64 65 64 20 74 6f 20 73 79 73 2e 70 61 74 68 0a 20 20 69 6d 70 6f 72 74 20 70 6b 67 5f 72 65 73 6f 75 72 63 65 73 0a>
docco: src/batman.coffee -> docs/batman.html

http://rtomayko.github.com/rocco/ - page not found

rtomayko/rocco#56 - rocco issue

http://rtomayko.github.com/rocco/rocco.html - site

/usr/local/lib/node_modules/docco/lib/docco.js:7
throw error;
^
Error: ENOENT, open '-h'

A fixed position element has obvious size limitations, so dealing with large file sets the list becomes unwieldy. This issue is more prevalent when dealing with hierarchical output (as is possible with pulls #45 and #49).

A simple overflow: auto CSS addition would be an obvious first step. However, an expandable navigation would greatly help hierarchical output.

I would also love to have a simple fuzzy name filter (like Textmate's cmd+t).

I will start a branch and make a pull req tomorrow for the CSS overflow change. Hopefully this week I will have time for the filter. If you have any thoughts or comments, contribute here.

Is there any reason we shouldn't set headers' margin-top to 0?

It seems like docco isn't trying to parse the options it's given and just tries opening them as files:

node_modules/docco/bin/docco --output docs/test test/test-markdown.coffee

/Users/mark/Dropbox/prog/coffeescript/markdown-coffee/node_modules/docco/lib/docco.js:7
        throw error;
              ^
Error: ENOENT, open '--output'

Example .coffee:

###* 
This is my comment
###
window.hello = "World"

Docco outputs the * as an <h2> and This is my comment as code. Also outputs a # as an <h2> as well.

I know using JSDoc and Docco together seems strange, but they're coming from Closure Compiler annotations.

I am using docco for my Jasmine specs and it works really great!

But is there a way to mark sections I don't want in the final output?

That would make the documentation 100% clean because then only API code will be seen in the documentation.

Also it would be good for other cases to ignore sections.

Thanks.

A couple of issues actually, but they are probably connected

(1) Jibberish code on the left side, just above the "Extends" header.
http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html#section-54

(2) The code on the right side is missing for the "In" header.
http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html#section-113

(3) Similar jibberish on the left side just above the "Throw" header, and things start to lose alignment ...
http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html#section-117

I ran npm install docco and ran into the confusing "Error: write EPIPE" because pygments wasn't installed correctly. But this issue #42 was closed months ago.

I didn't realize docco in git is very different from the version npm installed from February 2011, even though they share version 0.3.0 in package.json. To clarify, perhaps change package.json from

  "version":      "0.3.0",

to something like

  "version":      "0.3.99 development",

(Or make npm git-aware so users can install HEAD ...)

I have setup all dependencies,

pygmentize dict/index.coffee

works nicely. But:

$ docco/bin/docco dict/index.coffee 

node.js:63
    throw e;
    ^
Error: EPIPE, Broken pipe
    at Stream._writeImpl (net:300:14)
    at Stream._writeOut (net:739:25)
    at Stream.write (net:672:17)
    at /home/andi/.node_libraries/docco/lib/docco.js:73:20
    at /home/andi/.node_libraries/docco/lib/docco.js:11:14
    at fs:82:13
    at node.js:772:9

I don't use npm, is this the problem?

example:

docco ./jquery/core.js

output : ./docs/jquery/core.js

-bcj is treated as -i, while -jcb works as expected.

I'm guessing this is happening because -j needs to be first.

Pretty simple to reproduce: https://gist.github.com/1360459

Input character was U+1F603 (U+D83D U+DE03) “SMILING FACE WITH OPEN MOUTH,” encoded as F0 9F 98 83 in UTF-8; output was U+FFFD “REPLACEMENT CHARACTER,” encoded as EF BF BD in UTF-8.

Example: http://img.skitch.com/20101025-jjwj2adre6xi4tgyqqted6afwg.png

I think it would be worthwhile to have a reference in the footer to the fact the page was generated with docco. I've gotten a whole bunch of feedback from people who 'love how I've created my source documentation', which isn't really cool because I did little more than run docco audio.js.

I feel like credit should be given where credit is due y'know? And I don't like the idea of manually adding an attribution every time I regenerate the source, that sort of sucks.

tl;dr: Docco probably shouldn't claim GFM since it uses showdown.js

From http://github.github.com/github-flavored-markdown/ :

URL autolinking

GFM will autolink standard URLs, so if you want to link to a URL (instead of setting link text), you can simply enter the URL and it will be turned into a link to that URL.

This comment supports autolinking, but docco does not. This is probably because showdown.js does not autolink either. Docco claims GFM support, but showdown does not, so maybe just say Docco supports markdown?

While I was working on support for Windows, I was unable to completely make the Cakefile tasks portable, in part because of the install task, which is pretty command line heavy.

I've never had the opportunity to use the install task, because it is very easy to install docco using npm, so I'm wondering if it can be removed?

Looking over the commit history, it appears that docco did not originally ship with an npm package.json file. Did this task become obsolete when the npm package was introduced?

If I were to remove the install task, it would be fairly straightforward to fix the doc task, using readFile and a regex replacement, which would complete Docco Windows support.

@jashkenas can you comment on this?

Was surprised that this was the case. Is this just not done yet, or is there a specific reason why multiline comments aren't supported?

It would be nice to be able to ignore Sprockets directives in code. I've got a hacked-up version of Sprockets running now that parses require directives for CoffeeScript projects (Sprockets 2.0 will handle this natively in the same way, I believe) as such:

#= require "FooPackage"
#= require "BarPackage"

These just show up as an ugly block before the source of the file. I'm not sure how best to architect a solution to this, which is why I haven't just submitted a pull request. docco.coffee:161 has l.comment_filter, but I'm not sure whether or not it would make sense to ignore all comments that begin immediately with = or have a per-language setting or have a command-line flag. Perhaps a user-configurable list of regular expressions for comments to ignore?

Look at the documentation for a new quick project this morning: http://eegg.github.com/mustache.coffee/

At the function escape, pygments appears to incorrectly parse a regex literal. After that, docco does not split the returned text on the #DIVIDER markers. Consequently the last four sections show undefined code.

I guess it's not a problem with my code/documentation; it compiles fine.

Since node and npm now officially support Windows platforms it would be great to see docco join in. I'm currently uninstalling cygwin on my Windows machines as node was the only reason it was installed in the first place. However, I was gutted to see that docco doesn't run on Windows.

Would it be possible to make the few changes required to support Windows? I primarily work on OS X/Ubuntu, but it would be great if I could build the docs for my projects on any machine.

After a quick look it appears to be mainly down to using mkdir -p and unix paths (e.g. src/*.js) not working as expected, but there could be other bugs.

I've been trying to get Docco working on Windows 7. I have the latest version of Node.

I tried using the following tutorial: http://bateru.com/news/2012/03/how-to-install-docco-on-windows-7/

Following everything apart from the Paths. I only added the python paths ';C:\python27;C:\Python27\Scripts;' since Node is already available from the command line.

Everything installs but when I try to use docco, I get

Error: ENOENT, no such file or directory 'c:\Users\user\Downloads\docco\docs\docco.css'

Hi,

I've done all the work to get docco run on my windows machine

• python(2.7.3)
• nodejs(node-v0.8.5-x86.msi)
• coffee([email protected])
• pygment(Pygments-1.5-py2.7.egg)
• docco([email protected])

But when calling docco with a sample file, I get an error
"Cannot call method 'sort' of undefined" at sources=process.ARGV.sort(); line 141.

Do you have any idea?
Works better on linux?

Thank you
Andreas

Hi,

I have currently setup docco on my windows machine and I was able to generate annotated source for my .js file. However, I have a couple of questions related to docco

1. Currently when i run docco "myfilename.js", by default it generates the annotated source html doc under "docs/" director within the same folder where "myfilename.js" exists, is it possible to specify a custom output path for generating our documents? (something like docco myfilename.js /home/user/docs/)

2. Is it possible to generate docs for all the .js file within a directory by running a command like "docco *.js"

Thanks

The underscore.coffee page, which neatly separates the code and comments, is an interesting example of literate programming:

http://jashkenas.github.com/coffee-script/documentation/docs/underscore.html

However, I had to jump through a number of hoops (eg, trying different browsers, scaling the page, using landscape mode) before I could print it. It would be nice if it were printable in common browsers by default. jashkenas suggests handling this by adding "print" styles to the default CSS.

It would also be nice if there were a way to move the vertical division between the comments and code (eg, by wrapping the comments). However, that might be a bit more difficult.

Finally, I should note that an underlying problem here is that some of the code lines are (IMHO) unreasonably long. It would be trivial to check line lengths and raise a warning. Of course, getting developers to pay attention is another matter :-).

Two small issues with http://jashkenas.github.com/docco/#section-5:

Highlights a single chunk of CoffeeScript code, using Pygments over stdio,
and runs the text of its corresponding comment through Markdown, using
the Github-flavored-Markdown modification of Showdown.js.

First, it looks like you're not using GFM anymore: e53a2be.

Second, the Showdown.js link is broken and points to a domain-parking page. Maybe you could link to this mirror on GitHub.

please add Pygments to requirements for docco (using easy_install Pygments) otherwise the code part will have only undefined

Would be nice to call docco src/*.coffee from the terminal, and have the docs output inserted into the current working directory. (Maybe soon add a -o flag for setting the output directory)

It would seem that URL references e.g.

[Google][1], [1]: http://www.google.com
[GitHub][], [github]: http://www.github.com

only work within the single block-comment in which they are declared?

For example:

# Look at this link to [Google][]! 
#
# [google]: http://www.google.com

would work, but

# Look at this link to [Google][]!

# [google]: http://www.google.com

wouldn't.

Unless I'm doing something heaps wrong (and please tell me if I am), this means that one of the main possible benefits of using them - being able to refer to them multiple times in a document - doesn't work.

Would there be a way to gather all the URL references and use them throughout the documentation?

In section 12, link to hashbang point to "http://en.wikipedia.org/wiki/Shebang_(Unix" instead of "http://en.wikipedia.org/wiki/Shebang_(Unix)"

Environment:
OS: ArchLinux
Node: v0.6.6
npm: v1.1.0-beta-4

I installed docco through npm. When I tried to run docco test.js, I received the following error:

node.js:201
    throw e; // process.nextTick error, or 'error' event on first tick
Error: write EPIPE
    at errnoException (net.js:632:11)
    at Object.afterWrite [as oncomplete] (net.js:470:18)

Even after installing python-pygments (sudo pacman -S python-pygments), the error is still there.

Only a css file is generated in docs folder.

please add github repository and license to the docs.

Hi :)

Docco can't build docs with the newest version of node (0.1.94)
Error message:

sys.exec has moved to the "child_process" module. Please update your source code.
TypeError: Object Error: EPIPE, Broken pipe
    at Stream._writeOut (net:640:22)
    at Stream.write (net:540:17)
    at highlight (eval at <anonymous> (/usr/local/lib/coffee-script/lib/coffee-script.js:58:25))
    at eval at <anonymous> (/usr/local/lib/coffee-script/lib/coffee-script.js:58:25)
    at fs:52:23
    at node.js:176:9
 has no method 'read'
    at /usr/local/bin/docco:9:44
    at ChildProcess.<anonymous> (child_process:82:21)
    at ChildProcess.emit (events:32:26)
    at ChildProcess.onexit (child_process:114:12)
    at node.js:176:9

As per conversations from #110, the "Jump to..." menu does not work on touch devices.

At current, on Android, as soon as you touch your finger to the "Jump To" button, the menu shows but the first item begins behaving like a click event, and so a tap on the "Jump To" button just takes you to the first result in the menu.

The desired behaviour may be to make the jump to menu only work on click rather than on hover for ALL devices.

The docs that docco [file] outputs all have undefined for every code snippet. See file.js and the resulting file.html.

Proposal:

Whenever any line in a block of comments matches a regex, e.g.

<ref:([^>\s]+)>

have the fragment id for that block be ("_" + group1).

If a patch were submitted, should it be merged?