{"id":13624830,"url":"https://github.com/brynbellomy/otis","last_synced_at":"2025-08-11T00:09:18.561Z","repository":{"id":4620596,"uuid":"5764456","full_name":"brynbellomy/otis","owner":"brynbellomy","description":"Documentation generator for Javascript, CoffeeScript, C, C++, Objective-C, Ruby, Python, AS3, Java, and everything else ever.","archived":false,"fork":false,"pushed_at":"2012-12-01T01:09:49.000Z","size":440,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-03T05:15:19.614Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://brynbellomy.github.com/otis","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brynbellomy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-11T12:15:22.000Z","updated_at":"2024-02-18T23:19:26.000Z","dependencies_parsed_at":"2022-08-19T16:21:06.843Z","dependency_job_id":null,"html_url":"https://github.com/brynbellomy/otis","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brynbellomy%2Fotis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brynbellomy%2Fotis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brynbellomy%2Fotis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brynbellomy%2Fotis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brynbellomy","download_url":"https://codeload.github.com/brynbellomy/otis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252784312,"owners_count":21803646,"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-08-01T21:01:46.914Z","updated_at":"2025-05-06T23:24:16.093Z","avatar_url":"https://github.com/brynbellomy.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# // otis\n\n## *(the next documentation generator)*\n\nnamed after the documenter of the dock of some nameless bay somewhere.\n\n**supported languages:**\n\n- javascript\n- coffeescript\n- objective-c\n- c / c++\n- c#\n- java\n- python\n- ruby\n- gaelic.  i think.\n\n# how sick is this, bro?\n\n*real sick*.  check it:\n\n- **auto-append custom CSS to every single documentation build**  \n  never have to waste any suffering on crappy or hyper-corporate color schemes\n  again. hell, make your docs look like the dead sea scrolls or something.\n  sky's the limit.\n- **syntax highlighting:** pygments.\n- **templating:**\n  [visionmedia/consolidate.js](http://github.com/visionmedia/consolidate.js),\n  which means just about every template engine ever is supported.\n    - [jade](http://github.com/visionmedia/jade) templates are provided out of\n      the box.  that's right.  so sick you just threw up.\n- **3 markdown engines** you can choose from:\n    - showdown.js\n    - [github-flavored-markdown](http://github.com/isaacs/github-flavored-markdown)\n    - [marked](https://github.com/chjj/marked)\n    - it wouldn't be hard at all to add support for more.  the API is simply a\n      synchronous function that takes one argument and returns the rendered markdown.\n- **simple project config files**  \n  uses node.js's native module `require` architecture to store settings\n  per-project for generating documentation.  that way you can just type `otis`\n  in the project root -- nothing more.  finally, you'll be able to get that\n  frontal lobotomy without inconveniencing your coworkers -- you've earned it!\n- **simple global config files**  \n  ...in case you know you'll always want this or that flag specified, no matter\n  what you're documenting.\n- **a cakefile task**  \n  because who doesn't love `cake watch`ing?\n- **it documents Objective-C code**  \n  why?  because that's my godawful day job.  **otis** will also help you document\n    1. tearing the wings off of angels, \n    2. grinding little puppies into big mac meat patties\n    3. etc.\n\n\n\n# requirements\n\n[Pygments (http://pygments.org)](http://pygments.org)\n\n\n\n# installation\n\n(this *should* `easy_install` **pygments** for you, but if not, it's not very hard to get it up and running manually)\n\n```sh\nnpm install -g otis\n```\n\n\n\n# usage\n\n```sh\n$ otis [use \u003cconfig\u003e] [options] [files to document]\n```\n\nwhen `use \u003cconfig\u003e` is present, **otis** will attempt to load config files in the\nfollowing order:\n\n- ~/.otis/otis.config.js\n- ~/.otis/otis.config.\\\u003cconfig\\\u003e.js\n- ./otis.config.\\\u003cconfig\\\u003e.js\n\n... and will bail if neither of the latter two could be found, assuming you\nhave made a grave error of some kind.  **otis** will not look for\n`./otis.config.js` under these circumstances.\n\nwhen there is no 'use \u003cconfig\u003e' argument specified, otis will use this order\ninstead:\n\n- `~/.otis/otis.config.js`\n- `./otis.config.js`\n\n## + config files\n\n**otis** loads all of the config files it can find and merges them together,\ngiving \"override precedence\" to the files listed closer to the bottom in the\ntwo lists above.\n\nso for example, if you have a home directory **otis.config.js** and also a\ncurrent directory **otis.config.js**, otis will load both, and will allow\nanything in the current directory config to override the home directory config.\n\n## + input files\n\nthey're just your typical input files.  four little NBs, though:\n\n- the list of files is relative to the path you give in the `inDir` argument\n  (if you give one).\n- any of the files given can also be directories, in which case **otis** will\n  recurse into them.\n- folder structure inside the input directory is preserved into the output\n  directory.\n- output file names are simply **\\\u003coriginal filename with ext\\\u003e.html**.\n\n\n## + options (you can put any of these in an otis.config.js file!)\n\n```\n  -i, --inDir           Input directory (defaults to current dir)\n  -o, --outDir          Output directory (defaults to ./doc)\n  -t, --tplDir          Directory containing dox.\u003cext\u003e, code.\u003cext\u003e, and tmpl.\u003cext\u003e\n  -e, --tplEngine       Template parser (see github.com/visionmedia/consolidate.js)\n  -n, --tplExtension    Template file extension\n  -m, --markdownEngine  Only two choices, cowboy.\n  -u, --onlyUpdated     Only process files that have been changed\n  -c, --colourScheme    Color scheme to use (as in pygmentize -L styles)\n  -y, --css             CSS file to include after pygments CSS (you can specify this flag multiple times)\n  -T, --tolerant        Will parse comments without a leading ! (ex: \"/**! ...\")\n  -w, --watch           Watch on the input directory for file changes (experimental)\n  -I, --ignoreHidden    Ignore hidden files and directories (starting with . or _)\n  -s, --sidebarState    Whether the sidebar should be open or not by default\n  -x, --exclude         Paths to exclude\n  -W, --writeConfig     Write 'otis.config.js' in PWD using the options provided.\n  -h, --help            Show this help text.\n```\n\n\n\n# otis.config.js dissection\n\nyou can have **otis** auto-generate a config file for you in the current\ndirectory freezing whatever flags you pass to it into a reusable command.\nif the current directory or `~/.otis` contain an `otis.config.js` file, all you\nhave to type to generate beautiful, easily-navigable documentation is `otis .`\n(mind the dot)\n\nbut, just for reference's sake, an `otis.config.js` file will basically look\nlike this:\n\n```js\nmodule.exports = {\n  inDir: './',\n  outDir: './doc',\n  tplDir: require(\"path\").join(process.env.HOME, '.otis', 'templates'),\n  tplEngine: 'jade',\n  tplExtension: 'jade',\n  markdownEngine: 'showdown',\n  onlyUpdated: false,\n  colorScheme: 'friendly',\n  tolerant: false,\n  ignoreHidden: true,\n  sidebarState: true,\n  exclude: 'otis.config.js,*.md,doc,node_modules,bin'\n};\n```\n\nyep, just a regular old **node.js** module.\n\n**note** that the keys on this object correlate 1 to 1 with the available\ncommand-line options.  that's the plan moving forward indefinitely.\n\n\n\n# ~/.otis\n\nthere's currently only one file that **otis** is hard-coded to look for in\n`~/.otis`, namely, `otis.config.js` (or `otis.config.\u003cconfig\u003e.js` as the case\nmay be).\n\nhowever, it's also a great place to store your custom templates, custom css\nfiles, etc. as well.  only difference is that you have to tell **otis** (yes,\nin a config file) that he should look there for them.\n\ndon't waste your `~/.otis`.  put it to good use.\n\n\n\n# examples\n\n## 1. process every file in the current directory into ./doc\n\n```sh\n$ otis .\n```\n\n## 2. process files in ./src to ./documents\n\n```sh\n$ otis -i src -o documents\n```\nor:\n```sh\n$ otis -o documents src\n```\nor:\n```sh\n$ otis -o documents src/*\n```\n\nnote that in the first example, the contents of `src` will be mapped directly\ninto `documents` whereas in the second and third examples, the files will be\ncreated inside `documents/src`.\n\n## 3. generate otis docs\n\ni will bequeath to you the secret, ancient command i use to generate\n[this project's documentation](http://brynbellomy.github.com/otis).  it does\nall of the following:\n\n- uses **jade** as the templating engine\n- uses custom **jade** templates sitting in my home directory instead of\n  something ugly and hardcoded like with most doc tools\n- uses the \"friendly\" color scheme from pygments\n- modifies the \"friendly\" color scheme with custom CSS\n- outputs to a directory on the `gh-pages` branch of this repo\n- ignores files starting with `_` or `.`\n- excludes the `node_modules` directory, the `README.md` file, and a few other\n  things\n- ignores comment blocks that don't begin with a \"!\"\n\nthe command is:\n\n```sh\n$ otis .\n```\n\nhahaaaaa, gotcha!  see?  use **otis.config.js** files.  they're great.\n\n\n# addendum\n\n## + strict-mode and tolerant-mode\n\nyou may not want every single comment in your code to end up as a line in your\ndocumentation.  **otis** assumes that to be the case by default and will only\nprocess a comment as documentation if the very first character after the\ncomment delimiter is `!` (an exclamation point).\n\nso, depending on the language, something like the following:\n\n```c++\n//! slkdfjslkdjf\n```\n\n```c++\n/*!\n * alskdfjlaskjdf\n */\n```\n\n```coffeescript\n###!\nasldkfjalskdjf\n###\n```\n\n**if you want to disable this behavior so that all comments become\ndocumentation,** just use the `--tolerant` or `-T` flag on the command line, or\ninclude `tolerant: true` in your `otis.config.js` file.\n\n\n\n## + color schemes\n\nthese are exactly as in `pygmentize -L styles`:\n\n- monokai\n- manni\n- rrt\n- perldoc\n- borland\n- colorful\n- default\n- murphy\n- vs\n- trac\n- tango\n- fruity\n- autumn\n- bw\n- emacs\n- vim\n- pastie\n- friendly\n- native\n\n\n\n# authors / contributors\n\n**at the moment, only:**\n\nbryn austin bellomy \u003c [bryn.bellomy@gmail.com](mailto:bryn.bellomy@gmail.com) \u003e\n\n\n# forefathers / ancestors\n\n**otis owes unrepayable debts to:**\n\n- [jashkenas / **docco**](http://jashkenas.github.com/docco/)\n- [mbrevoort / **docco-husky**](https://github.com/mbrevoort/docco-husky)\n- [jbt / **docker**](http://jbt.github.com/docker)\n\n\n\n# license (wtfpl)\n\n```\nDO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE\nVersion 2, December 2004\n\nCopyright (C) 2004 Sam Hocevar \u003c[sam@hocevar.net](mailto:sam@hocevar.net)\u003e\n\nEveryone is permitted to copy and distribute verbatim or modified \ncopies of this license document, and changing it is allowed as long \nas the name is changed. \n\nDO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION\n\n0. You just DO WHAT THE FUCK YOU WANT TO. \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrynbellomy%2Fotis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrynbellomy%2Fotis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrynbellomy%2Fotis/lists"}