{"issue":{"created_at":"2011-11-26T23:13:03Z","state":"open","updated_at":"2011-11-28T00:02:33Z","comments":2,"user":{"gravatar_id":"dd56da509c21eebb967777a9dbcce437","id":154510,"url":"https://api.github.com/users/jterrace","login":"jterrace","avatar_url":"https://secure.gravatar.com/avatar/dd56da509c21eebb967777a9dbcce437?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png"},"body":"This creates a root directory called doc. It has a Makefile that does the following:\r\n1. Downloads [jsdoc-toolkit](http://code.google.com/p/jsdoc-toolkit/)\r\n2. Clones [jsdoc-for-sphinx](https://github.com/stdbrouw/jsdoc-for-sphinx)\r\n3. Uses jsdoc-toolkit and the sphinx template to output sphinx files for three.js\r\n4. Runs a sphinx build to produce HTML output\r\n\r\nThis adds documentation directly into the JS source files. Is this acceptable? I think it's the easiest way to maintain documentation since it's collocated with the code itself.\r\n\r\nThis is an example of the output that gets produced:\r\nhttp://www.cs.princeton.edu/~jterrace/temp/threejs/generated/core/THREE.Color.html\r\nI have only documented the THREE.Color class so far, so this is just an example page. This is what the documented source code looks like:\r\nhttps://github.com/jterrace/three.js/blob/2960863897af11705075377ffb7fefef28266f68/src/core/Color.js\r\n\r\nTo be clear: **this is not ready to merge**. I just wanted to open this up to get comments since I don't want to spend the time documenting the rest of the project if this is not the route the maintainers want to take. I think this would be a great way to generate some nice documentation, and sphinx is also great for writing tutorials and examples.","assignee":null,"id":2357534,"number":801,"pull_request":{"patch_url":"https://github.com/mrdoob/three.js/pull/801.patch","html_url":"https://github.com/mrdoob/three.js/pull/801","diff_url":"https://github.com/mrdoob/three.js/pull/801.diff"},"labels":[],"title":"Adds Documentation Generation using jsdoc-toolkit and Sphinx","closed_at":null,"html_url":"https://github.com/mrdoob/three.js/issues/801","milestone":null,"url":"https://api.github.com/repos/mrdoob/three.js/issues/801"},"action":"created","comment":{"created_at":"2011-11-28T00:02:33Z","updated_at":"2011-11-28T00:02:33Z","user":{"gravatar_id":"dd56da509c21eebb967777a9dbcce437","id":154510,"url":"https://api.github.com/users/jterrace","login":"jterrace","avatar_url":"https://secure.gravatar.com/avatar/dd56da509c21eebb967777a9dbcce437?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png"},"body":"I agree that the code becomes larger, but how else do you plan to document the API? Since it's a moving target, trying to maintain documentation separate from the code is a nightmare. I really feel that the benefit really outweighs the drawback.","id":2891227,"url":"https://api.github.com/repos/mrdoob/three.js/issues/comments/2891227"}}