{"id":13462931,"url":"https://github.com/nevir/groc","last_synced_at":"2025-05-16T05:05:59.196Z","repository":{"id":57254337,"uuid":"2854930","full_name":"nevir/groc","owner":"nevir","description":"Documentation generation, in the spirit of literate programming.","archived":false,"fork":false,"pushed_at":"2019-06-05T16:41:28.000Z","size":1686,"stargazers_count":580,"open_issues_count":79,"forks_count":131,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-05-06T02:40:21.344Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://nevir.github.com/groc/","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nevir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-11-26T09:29:14.000Z","updated_at":"2025-02-14T15:50:03.000Z","dependencies_parsed_at":"2022-08-31T08:31:51.197Z","dependency_job_id":null,"html_url":"https://github.com/nevir/groc","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevir%2Fgroc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevir%2Fgroc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevir%2Fgroc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevir%2Fgroc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nevir","download_url":"https://codeload.github.com/nevir/groc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471061,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:41.330Z","updated_at":"2025-05-16T05:05:54.183Z","avatar_url":"https://github.com/nevir.png","language":"CoffeeScript","readme":"# groc\n\nGroc takes your _documented_ code, and in an admission that people aren't machines, generates\ndocumentation that follows the spirit of literate programming.  Take a look at the\n[self-generated documentation](http://nevir.github.com/groc/), and see if it appeals to you!\n\nIt is very heavily influenced by [Jeremy Ashkenas](https://github.com/jashkenas)'\n[docco](http://jashkenas.github.com/docco/), and is an attempt to further enhance the idea (thus,\ngroc can't tout the same quick 'n dirty principles of docco).\n\n\n## Maintainers\n\nGroc, unfortunately, does not have any active maintainers. If you are interested in picking up the\ntorch, please toss me an email (ian@nevir.net).\n\n\n## What does it give you?\n\nGroc will:\n\n* Generate documentation from your source code, by displaying your\n  [Markdown](http://daringfireball.net/projects/markdown/) formatted comments next to the code\n  fragments that they document.\n\n* Submit your project's documentation to the [github pages](http://pages.github.com/) for your\n  project.\n\n* Generate a searchable table of contents for all documented files and headers within your project.\n\n* Gracefully handle complex hierarchies of source code across multiple folders.\n\n* Read a configuration file so that you don't have to think when you want your documentation built;\n  you just type `groc`.\n\n\n## How?\n\n### Installing groc\n\nGroc depends on [Node.js](http://nodejs.org/).  Once you have those installed - and assuming that \nyour node install came with [npm](http://npmjs.org/) - you can install groc via:\n\n```bash\n$ npm install -g groc\n```\n\nFor those new to npm, `-g` indicates that you want groc installed as a global command for your\nenvironment.  You may need to prefix the command with sudo, depending on how you installed node.\n\n\n### Using groc (CLI)\n\nTo generate documentation, just point groc to source files that you want docs for:\n\n```bash\n$ groc *.rb\n```\n\nGroc will also handle extended globbing syntax if you quote arguments:\n\n```bash\n$ groc \"lib/**/*.coffee\" README.md\n```\n\nBy default, groc will drop the generated documentation in the `doc/` folder of your project, and it\nwill treat `README.md` as the index.  Take a look at your generated docs, and see if everything is\nin order!\n\nOnce you are pleased with the output, you can push your docs to your github pages branch:\n\n```bash\n$ groc --github \"lib/**/*.coffee\" README.md\n```\n\nGroc will automagically create and push the `gh-pages` branch if it is missing.\n\nThere are [additional options](http://nevir.github.com/groc/cli.html#cli-options) supported by\ngroc, if you are interested.\n\n\n### Configuring groc (.groc.json)\n\nGroc supports a simple JSON configuration format once you know the config values that appeal to you.\n\nCreate a `.groc.json` file in your project root, where each key maps to an option you would pass to\nthe `groc` command.  File names and globs are defined as an array with the key `glob`.  For\nexample, groc's own configuration is:\n\n```json\n{\n  \"glob\": [\"lib/**/*.coffee\", \"README.md\", \"lib/styles/*/style.sass\", \"lib/styles/*/*.jade\"],\n  \"github\": true\n}\n```\n\nFrom now on, if you call `groc` without any arguments, it will use your pre-defined configuration.\n\n\n## Literate programming?\n\n[Literate programming](http://en.wikipedia.org/wiki/Literate_programming) is a programming\nmethodology coined by [Donald Knuth](http://en.wikipedia.org/wiki/Donald_Knuth).  The primary tenet\nis that you write a program so that the structure of both the code and documentation align with\nyour mental model of its behaviors and processes.\n\nGroc aims to provide a happy medium where you can freely write your source files as structured\ndocuments, while not going out of your way to restructure the code to fit the documentation.\nHere are some suggested guidelines to follow when writing your code:\n\n* Try to keep the size of each source file down.  It is helpful if each file fulfills a specific\n  feature of your application or library.\n\n* Rather than commenting individual lines of code, write comments that explain the _behavior_ of a\n  given method or code block.  Take advantage of the fact that comments can span that method.\n\n* Make gratuitous use of lists when explaining processes; step by step explanations are extremely\n  easy to follow!\n\n* Break each source file into sections via headers.  Don't be afraid to split source into even\n  smaller files if it makes them more readable.\n\nWriting documentation is _hard_; hopefully groc helps to streamline the process for you!\n\n\n## Known Issues\n\n* Groc does not fare well with files that have very long line lengths (minimized\n  JavaScript being the prime offender).  Make sure that you exclude them!\n\n\n## What's in the works?\n\nGroc wants to:\n\n* [Fully support hand-held viewing of documentation](https://github.com/nevir/groc/issues/1).  It\n  can almost do this today, but the table of contents is horribly broken in the mobile view.\n","funding_links":[],"categories":["Documentation","Repository","CoffeeScript"],"sub_categories":["Documentation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevir%2Fgroc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnevir%2Fgroc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevir%2Fgroc/lists"}