nevir / groc Goto Github PK
View Code? Open in Web Editor NEWDocumentation generation, in the spirit of literate programming.
Home Page: http://nevir.github.com/groc/
License: MIT License
Documentation generation, in the spirit of literate programming.
Home Page: http://nevir.github.com/groc/
License: MIT License
Anyone interested in helping to port this to .net?
It seems that groc just ignore the file.
It appears to be having issues installing the "autorequire" node package from the npmjs repository.
Error: No compatible version found: autorequire@'>=0.3.0- <0.4.0-'
I'm a new user to groc, here is my setup:
I have a README.md
file in the same directory where I run groc
, but the generated doc/
folder does not have any index file, nor do I see the README content anywhere. This results in separate HTML files with no clear entry point. What is the intended behavior when a README file is present? Does it produce a index.html
file in the root of the generated documentation directory?
Here's how I'm calling groc
:
groc -e "node_modules/**" --no-whitespace-after-token -i ./README.md "**/*.coffee"
Even with the explicit -i
option, it still doesn't seem to pickup the README file. Am I missing something?
I just noticed this issue a few days ago, but it seems like the latest groc has broken with the latest uglify-js (and its dependency on source-map). I created a fork of groc to test with uglify-js 1.x.x and it installs fine.
All relevant info below:
npm http GET https://registry.npmjs.org/groc
npm http 304 https://registry.npmjs.org/groc
npm http GET https://registry.npmjs.org/coffee-script
npm http GET https://registry.npmjs.org/colors
npm http GET https://registry.npmjs.org/fs-tools
npm http GET https://registry.npmjs.org/optimist
npm http GET https://registry.npmjs.org/showdown
npm http GET https://registry.npmjs.org/glob
npm http GET https://registry.npmjs.org/spate
npm http GET https://registry.npmjs.org/uglify-js
npm http GET https://registry.npmjs.org/underscore
npm http GET https://registry.npmjs.org/autorequire
npm http 304 https://registry.npmjs.org/coffee-script
npm http 304 https://registry.npmjs.org/optimist
npm http 304 https://registry.npmjs.org/showdown
npm http 304 https://registry.npmjs.org/fs-tools
npm http 304 https://registry.npmjs.org/colors
npm http 304 https://registry.npmjs.org/glob
npm http 304 https://registry.npmjs.org/spate
npm http 304 https://registry.npmjs.org/underscore
npm http 304 https://registry.npmjs.org/uglify-js
npm http 304 https://registry.npmjs.org/autorequire
npm http GET https://registry.npmjs.org/graceful-fs
npm http GET https://registry.npmjs.org/inherits
npm http GET https://registry.npmjs.org/minimatch
npm http GET https://registry.npmjs.org/wordwrap
npm http GET https://registry.npmjs.org/underscore
npm http GET https://registry.npmjs.org/source-map
npm http 304 https://registry.npmjs.org/graceful-fs
npm http 304 https://registry.npmjs.org/inherits
npm http 304 https://registry.npmjs.org/minimatch
npm http GET https://registry.npmjs.org/sigmund
npm http 304 https://registry.npmjs.org/source-map
npm http GET https://registry.npmjs.org/lru-cache
npm http 304 https://registry.npmjs.org/underscore
npm http 304 https://registry.npmjs.org/wordwrap
npm ERR! error rolling back [email protected] Error: ENOTEMPTY, rmdir '/Users/jefulton/Documents/Projects/Nike/project/server/node_modules/groc/node_modules/fs-tools/node_modules/underscore'
npm ERR! Error: No compatible version found: source-map@'>=0.1.7- <0.2.0-'
npm ERR! Valid install targets:
npm ERR! ["0.0.0","0.1.0","0.1.1","0.1.2","0.1.3"]
npm ERR! at installTargetsError (/Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/lib/cache.js:496:10)
npm ERR! at next_ (/Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/lib/cache.js:446:17)
npm ERR! at next (/Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/lib/cache.js:423:44)
npm ERR! at /Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/lib/cache.js:416:5
npm ERR! at saved (/Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/lib/utils/npm-registry-client/get.js:151:7)
npm ERR! at Object.oncomplete (/Users/jefulton/nvm/v0.6.19/lib/node_modules/npm/node_modules/graceful-fs/graceful-fs.js:230:7)
npm ERR! You may report this log at:
npm ERR! <http://github.com/isaacs/npm/issues>
npm ERR! or email it to:
npm ERR! <[email protected]>
npm ERR!
npm ERR! System Darwin 10.8.0
npm ERR! command "node" "/Users/jefulton/nvm/v0.6.19/bin/npm" "install"
npm ERR! cwd /Users/jefulton/Documents/Projects/Nike/project/server
npm ERR! node -v v0.6.19
npm ERR! npm -v 1.1.24
npm ERR! message No compatible version found: source-map@'>=0.1.7- <0.2.0-'
npm ERR! message Valid install targets:
npm ERR! message ["0.0.0","0.1.0","0.1.1","0.1.2","0.1.3"]
npm http 304 https://registry.npmjs.org/sigmund
npm http 304 https://registry.npmjs.org/lru-cache
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! /Users/jefulton/Documents/Projects/Nike/project/server/npm-debug.log
npm not ok
npm not ok
I'm integrating groc
in my Makefile
, and even the default output is too verbose, so I'm missing a --silent
option.
If you think it could be useful, I could take a stab at it.
However, I don't know if it should set the trace level to WARN
or ERROR
. What do you think?
The error message is:
no autorequire.Loader behavior defined for node 0.10.1.
Firefox is pretty close to WebKit, but some of the transitions (or delays) aren't kicking in.
Hi first off I'm loving this. Was playing with docco but much prefer the menu and project handling in groc hope you keep developing this.
Possible small bug when I try to create files for a project the first folder is ignored and the files from it are placed in the root.
So if it do groc _.js utils/_js lib/*.js I get all the files but only one subfolder lib in the menu.
I have put an empty folder called blank in my project and run groc .js blank/.js utils/js lib/.js which gives me a root, a utils and a lib folder in the menu.
Cheers
Hi there,
I'm new to using node.js so apologies if this is just my ignorance and not a bug...
But having installed croc (which looks amazing btw! - i really want to run it :), i cannot get it to run.
node and pigments are installed (used docco fine), but running croc, it either fails silently or throws the following error:
node.js:201
throw e; // process.nextTick error, or 'error' event on first tick
^
TypeError: Object function glob(pattern, options, cb) {
if (typeof options === "function") cb = options, options = {}
if (!options) options = {}
if (typeof options === "number") {
deprecated()
return
}
var m = new Glob(pattern, options, cb)
if (options.sync) {
return m.found
} else {
return m
}
} has no method 'globSync'
at Object.CLI (/usr/local/lib/node_modules/groc/lib/cli.coffee:102:18)
at Object.<anonymous> (/usr/local/lib/node_modules/groc/bin/groc:3:17)
at Module._compile (module.js:432:26)
at Object..js (module.js:450:10)
at Module.load (module.js:351:31)
at Function._load (module.js:310:12)
at Array.0 (module.js:470:10)
at EventEmitter._tickCallback (node.js:192:40)
had a good google and can't find anything related to that error.
I have stub README.md and almost empty .groc.json:
{
"globs": ["./*.js"]
}
look in anyway familiar?
Is there any way to remove the blockquotes from comments div and put it in the code div?
It would be nice to support extension-less files, with perhaps a command-line option that tells groc what is the file's language.
For example, I'd like to document my Cakefile, but I get:
Cakefile is not in a supported language, skipping.
If I could tell groc that it's in CoffeeScript, it would probably work.
The toolbar is shifted too far to the left if there's a traditional scrollbar visible. This makes the auto-scale-down portion of the layout look bad.
Depending on how much my hatred of coffeescript gets in the way I may make a pull request for this.
I'm using the Snockets module to handle js concatenation and it uses the following to indicate a dependency in coffeescript files.
Is there a way to mark the code so it doesn't put it on the documentation side?
As a debugging aid, and for attribution. Should spit out the command that was run, a link to groc, etc
The current implementation is confusing
For example in the following JavaScript snippet
// Useful when interfacing with server-side languages like PHP that make
PHP does not appear in bold
Is there a trick to making a github view-source button appear next to the ToC?
Best i can tell, it is the "repository-url"
option, but i have supplied that and it is not displaying. Thoughts?
The styles do not render the left column with the comments in IE9. Please add support for this browser.
The ToC should save state across pages. Probably the best bet is to AJAX in the next page
I'm trying to use groc in a fairly standard Rails project. I've got the following config:
{
"glob" : ["app/assets/js/**/*.coffee", "lib/**/*.rb", "config/**/*.rb"],
"github" : false
}
When I run 'groc', it puts all of the child folders from these paths right in the /doc root, which I don't like. I stumbled into the --no-strip option, which generates the documentation into the correct child folders, as I like, but when I do so the Table of Contents don't work. It still renders the button, but clicking on it or trying to search doesn't do anything.
Am I missing something?
See #15 for one example
Make sure that we're giving the user enough information to diagnose what's wrong, and next steps
The current theme is halfassed; make it suck less.
Maybe a Solarized variant?
A convention for describing function arguments and their constraints would be super useful. Similar to javadoc/etc, but not as heavy?
When docs change, generate 'em!
Publishing documentation to github...
! /usr/local/lib/node_modules/groc/scripts/publish-git-pages.sh: 10: Syntax error: "(" unexpected
Ubuntu 11.04
It would be super cool if groc were to read the projects version + name, from the package.json
file in a node.js-project and append the version & name to the browser stitle. That way one could be sure that one isn't viewing outdated docs.
This is a request to copy over local images included in markdown files (or comments.) I can see two ways this could be done: simplify specify a new option to copy files/folders (a "to" and a "from") for static assets; or some mechanism to do this automatically by finding files and copying them when encountered in the markdown comments.
For example, if the following markdown code is encountered:
![reference image](./images/reference.jpg)
Groc could look at the URI and determine it is a local file. Then it can either store a collection of all of those images and copy them over at the end of the process (and optionally rewrite the link URLs).
Thoughts? (Right now I'm simply copying my "images" folder over using a bash script.)
Should have header navigation, but not file navigation.
If the idea is to create an enhanced version of docco, why not get rid of pygments in favor of something that does not need to be installed, such as prismjs.com
This way users would need one less step to get the documentation up and running.
aka minimized JavaScript. Just bail out for now.
Should it not support github or other flavours of markdown?
They'd be nice, wouldn't they?
The layout is somewhat there. Behavior is lacking:
Right now groc publishes to the root of gh-pages.
I would like to know if it's possible to make it export to other folders (i.e. a /docs folder inside gh-pages). If that's not currently possible, please consider this a feature request.
Thanks a lot!
I have groc setup and working great on one of my computers but when I go to re-generate the docs from my other computer they don't end up in ./doc
like they're supposed to ... they instead show up in whatever folder the file being processed was in. Here's my .groc.json file.... any thoughts why this would be happening on one machine but not another?
{
"glob": ["app.js", "kue/*.js", "routes/*.js", "utils/*.js", "tests/*.js", "README.md"]
, "except": ["*.min.js", "node_modules/**/*.js"]
, "out": "./doc"
, "index": "README.md"
, "github": false
}
Thanks so much—loving groc! Keep up the great work.
-Mac
Hi all,
I'm having some issues getting Groc running on Windows 8 x64.
I have three test files:
When I run 'groc ' against each file, I get the following errors for app.rb and app.js:
C:\nodeProjects\test>groc README.md
Generating documentation...
√ C:\nodeProjects\test\doc\index.html
√ Documentation generated
C:\nodeProjects\test>groc app.js
Generating documentation...
! Failed to highlight C:\nodeProjects\test\app.js as JavaScript: CreateProcessW:
The system cannot find the file specified.
C:\nodeProjects\test>groc app.rb
Generating documentation...
! Failed to highlight C:\nodeProjects\test\app.rb as Ruby: CreateProcessW: The s
ystem cannot find the file specified.
C:\nodeProjects\test>groc app.html
Generating documentation...
» C:\nodeProjects\test\app.html is not in a supported language, skipping.
√ Documentation generated
Any suggestions on what might be causing the 'CreateProcessW' errors when running against .JS and .RB files?
I ran groc several times and it was not picking up comments in my javascript files. I finally resorted to whitespace-after-token: false
in my .groc.json
and it worked. Why is whitespace-after-token
set to true as the default value? It seems really limiting to those who may or may not use spaces after //
tokens.
Run through some large set of the languages that pygments supports, configure and test them.
When you format your comments with emphasis or strong emphasis, the comment is displayed just like normal text. Please add rules for <em>
and <strong>
in the .sass styles.
hey there,
I'm writing a grunt task that generates docs and I was thinking of using groc. I was wondering if it's possible to use groc within another script as opposed to on the CLI.
In the TOC folders are mixed with markdown headers.
This makes it difficult to orientate.
I just tried adding LESS support in languages.coffee, using the CSS lexer (there's no LESS lexer), but I found an issue: CSS doesn't officially have single-line comments, so pygments doesn't work on them: http://pygments.org/demo/45468/. This makes Groc fail, because it can't find its segments separators in the highlighted code.
Is there a way to add block-comments support to groc?
LESS does have single-line comments(http://lesscss.org/#-comments), so I submitted a feature request to pygments to add a LESS lexer: https://bitbucket.org/birkenfeld/pygments-main/issue/780/add-a-less-lexer
In TOC when I expand a folder lets say "libs" then I see files like "libs/file1.js" "libs/file2.js" etc.
Since I expanded the libs folder it would be easier for the eyes if only the file names are listed and not the absolute path since going some levels deeper will bloat the TOC with all paths.
When clicking on an item in TOC it disappears due to page switch.
Would give a better user experience if it was displayed until I click outside of it.
It isn't behaving as expected.
Try groc --root "./vendor/symfony/src" "**/*.php"
in the Symfony project as an example
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.