convore.json/groups/python/twisteds-documentation/messages.json

[{"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346255.252954, "message": "Yeah that does seem to be the problem. :)", "group_id": 292, "id": 176927}, {"user_id": 12907, "stars": [], "topic_id": 7959, "date_created": 1298355216.3352489, "message": "All,", "group_id": 292, "id": 177387}, {"user_id": 1, "stars": [], "topic_id": 7959, "date_created": 1298346149.892776, "message": "Here's the general pattern I see of great docs in the Python community. They use Sphinx. They are split up into more informal tutorial-style sections, and then into API documentation enumerating all of the important attributes/methods/objects/etc.", "group_id": 292, "id": 176917}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346167.4167869, "message": "We're migrating to use Sphinx.", "group_id": 292, "id": 176920}, {"user_id": 6671, "stars": [{"date_created": 1298346293.807266, "user_id": 1}, {"date_created": 1298353145.1884129, "user_id": 13806}, {"date_created": 1298393332.830941, "user_id": 222}], "topic_id": 7959, "date_created": 1298346266.981143, "message": "I definitely *don't* have time for this conversation.  But convore has been surprisingly interesting.", "group_id": 292, "id": 176928}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298347361.7364609, "message": "but the lack of an API for manipulating, emitting, and rewriting ReST documents is a real problem for our conversion tool, and the ad-hoc nature of the conversion tool is a problem for getting new documents written.", "group_id": 292, "id": 176980}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346065.8217881, "message": "Twisted's documentation is widely regarded as poor or problematic, but it's unclear exactly what everyone wants from it and what could be done with the project's limited resources.  Seems to keep coming up in other convore conversations, so it should have its own topic.", "group_id": 292, "id": 176908}, {"user_id": 1, "stars": [], "topic_id": 7959, "date_created": 1298346182.3215401, "message": "Here's Flask: http://flask.pocoo.org/docs/ Sphinx. User's guide. API Reference.", "group_id": 292, "id": 176921}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346184.104429, "message": "I'm not really sold on it personally, as its main feature seems to be distracting people from writing actual docs :)", "group_id": 292, "id": 176922}, {"user_id": 1, "stars": [], "topic_id": 7959, "date_created": 1298346246.9212551, "message": "I barely have time for this conversation, let alone helping on a project like that :)", "group_id": 292, "id": 176925}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346480.723475, "message": "(although that could much more easily have been fixed in our current infrastructure, the people who stepped forward to actually *do* it wanted to use sphinx)", "group_id": 292, "id": 176939}, {"user_id": 1, "stars": [{"date_created": 1298346785.1009171, "user_id": 6671}, {"date_created": 1298360404.5608959, "user_id": 214}], "topic_id": 7959, "date_created": 1298346644.874989, "message": "Gah, gotta go, glad to see work being done on this front! Twisted is awesome and more people should know about its awesomeness :)", "group_id": 292, "id": 176946}, {"user_id": 14578, "stars": [], "topic_id": 7959, "date_created": 1298346882.3825181, "message": "well, glyph meant it's detracted from producing docs because most of our docs work has been stalled on converting our existing docs to ReST (which is not all that well-defined :)", "group_id": 292, "id": 176956}, {"user_id": 5701, "stars": [], "topic_id": 7959, "date_created": 1298346193.9717381, "message": "The library used to generate the css applied to documentation seems somewhat overvalued amongst the community of people who don't like Twisted's documentation. ;)", "group_id": 292, "id": 176923}, {"user_id": 1, "stars": [], "topic_id": 7959, "date_created": 1298346428.057323, "message": "Hmm", "group_id": 292, "id": 176935}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346202.101768, "message": "but if you'd like to help Twisted use sphinx there are _lots_ of bite-sized chunks of work you could help us out with.", "group_id": 292, "id": 176924}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346358.7176361, "message": "and here's what they will look like once someone does the work to move the sphinx migration forward: http://buildbot.twistedmatrix.com/builds/sphinx-html/sphinx-html-15760/contents.html", "group_id": 292, "id": 176932}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298347317.980722, "message": "Yeah.  If our docs were already in ReST I'm sure we'd be able to edit them just fine.", "group_id": 292, "id": 176976}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346315.488023, "message": "So here's what our docs look like now: http://twistedmatrix.com/documents/current/core/howto/index.html", "group_id": 292, "id": 176930}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346395.5330651, "message": "Actually I guess the analog page would be http://buildbot.twistedmatrix.com/builds/sphinx-html/sphinx-html-15760/projects/core/howto/index.html", "group_id": 292, "id": 176934}, {"user_id": 6543, "stars": [{"date_created": 1298359753.1823239, "user_id": 3617}], "topic_id": 7959, "date_created": 1298346701.4984629, "message": "sphinx is fantastic.. it doesn't really detract in any way from producing docs.. in fact you can use a prechewed theme if you dont care about creating custom css", "group_id": 292, "id": 176949}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298346441.642524, "message": "and that is the one thing that I thing sphinx really brings to the table for us, a doc index that looks better than http://twistedmatrix.com/documents/10.2.0/", "group_id": 292, "id": 176936}, {"user_id": 9229, "stars": [], "topic_id": 7959, "date_created": 1298349272.8537331, "message": "There's large chunks of the API that are undocumented, and given Twisted's kinda hard to wrap braincells around, it's not usually as easy as just looking at the source to figure it out...", "group_id": 292, "id": 177098}, {"user_id": 9229, "stars": [], "topic_id": 7959, "date_created": 1298349189.9184079, "message": "Here's something I've run into a number of times. How do I choose between twisted.web vs. twisted.web2? How do I make the call? Assuming I wish to, how do I use twisted.web2.client?", "group_id": 292, "id": 177090}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298349745.4017091, "message": "If you need a feature from web2 that isn't in twisted.web, help us port it back, or wait for us to get around to backporting it :)", "group_id": 292, "id": 177112}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298349837.342706, "message": "More and more of the useful stuff from web2 is available in twisted.web these days; for example, twisted.web.client.Agent is generally much better designed than twisted.web2.client, so we're getting more aggressive about deprecating it now.", "group_id": 292, "id": 177114}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298349875.004003, "message": "It hasn't been in the last couple of Twisted releases if you install Twisted via easy_install or pip.  Unfortunately it is packaged by OS packagers who slurp stuff straight out of version control and don't use release tarballs.", "group_id": 292, "id": 177115}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298349717.217865, "message": "we're getting rid of web2.", "group_id": 292, "id": 177110}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298349722.274302, "message": "The way you make the call is: use twisted.web.", "group_id": 292, "id": 177111}, {"user_id": 13806, "stars": [], "topic_id": 7959, "date_created": 1298354023.2410109, "message": "Ha! and I was just digging for a ssh server/client twisted.conch tutorial today. Convore is certainly a pleasant surprise.", "group_id": 292, "id": 177338}, {"user_id": 9229, "stars": [], "topic_id": 7959, "date_created": 1298353153.830116, "message": "It's great to see the API's going to get cleaned up. I guess this has been a shining example of what I'm talking about though: typically to understand large parts of the API you're going to have to log into IRC.", "group_id": 292, "id": 177299}, {"user_id": 12907, "stars": [{"date_created": 1298370289.4701209, "user_id": 13912}, {"date_created": 1298449271.4002481, "user_id": 6671}], "topic_id": 7959, "date_created": 1298355441.6517529, "message": "I don't think the documentation is that bad - its just describing some reasonably difficult concepts - tak e a look at eventlet, stackless, gevent - the documentation is equally inaccesible once you get past the 'hello world' examples - not because its written badly - bu because the concepts are not obvious due to the paradigm shift of event driven programming. Glyph - I'd be happy to help - personally - I think the docs are great, but lacking in pictorial explanation.", "group_id": 292, "id": 177389}, {"user_id": 115, "stars": [], "topic_id": 7959, "date_created": 1298360979.6217849, "message": "and I guess just incompleteness of methods, or why would you use this vs that... sorry I can't remember more specifically", "group_id": 292, "id": 177669}, {"user_id": 115, "stars": [], "topic_id": 7959, "date_created": 1298361000.6748199, "message": "also IIRC google would always bring up docs for an old version", "group_id": 292, "id": 177671}, {"user_id": 115, "stars": [], "topic_id": 7959, "date_created": 1298360950.9840081, "message": "IIRC some docs are written in first person, from the perspective of the class", "group_id": 292, "id": 177666}, {"user_id": 115, "stars": [], "topic_id": 7959, "date_created": 1298360962.6766601, "message": "that was new to me", "group_id": 292, "id": 177668}, {"user_id": 214, "stars": [], "topic_id": 7959, "date_created": 1298360634.8489561, "message": "@jpcalderone I don't have any particular opinion on Twisted's docs, but I don't think it's at all accurate to describe Sphinx as a \"library used to generate the CSS applied to documentation.\" Generating CSS is a pretty small part of what Sphinx does, relative to generating markup (in several possible output formats); it makes writing and maintaining the docs themselves easier.", "group_id": 292, "id": 177659}, {"user_id": 5701, "stars": [{"date_created": 1298391900.8764911, "user_id": 214}], "topic_id": 7959, "date_created": 1298380810.018141, "message": "@carljm: Hyperbole for rhetorical effect.  The point is that presentation is only as good as the content being presented.  Only a few contributors actually try to work on the content.", "group_id": 292, "id": 178921}, {"user_id": 2108, "stars": [], "topic_id": 7959, "date_created": 1298427582.91327, "message": "I haven't had a problem with the twisted docs.  But yeah, it could be prettier.", "group_id": 292, "id": 185532}, {"user_id": 9229, "stars": [], "topic_id": 7959, "date_created": 1298427538.0980339, "message": "@jpcalderone indeed worrying about the look isn't as important as the content - but sphinx does offer a bunch of useful tools for documenting Python APIs (for example cross-referencing, specific markups) that I've found useful for larger libraries.", "group_id": 292, "id": 185531}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298448688.764967, "message": "@Nettok Thanks for saying so.", "group_id": 292, "id": 186207}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298448871.746846, "message": "@r1chardj0n3s Our current documentation system (Lore) also has those features: since it's natively HTML, you can just hyperlink to cross-reference between different areas of the narrative documentation, or use <code class=\"API\"> to link to an API.  It's documented here:  http://twistedmatrix.com/documents/current/lore/howto/lore.html.", "group_id": 292, "id": 186210}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298448935.9969749, "message": "Sphinx seems to have slightly nicer index generation, but feature-wise I don't see Sphinx as making a big difference.  The real reasons we're migrating are: 1) it would be nice to stop maintaining twisted.lore, and 2) people who *claim* to want to write documentation seem to be happier writing ReST than writing HTML.", "group_id": 292, "id": 186211}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298449443.2917719, "message": "@bwghughes The biggest help for the docs right now would be getting us over the hump to migrate to Sphinx, I think.  Have a look at http://twistedmatrix.com/trac/report/15 and see if you can pick up some of the \"improve lore2sphinx output for...\" tickets.", "group_id": 292, "id": 186228}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298449183.457422, "message": "Point #1 is really the big one though, as the only people who have really made a substantial contribution to the docs in the last 3 years have used HTML: @jpcalderone on Twisted Web in 60 Seconds http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/index.html, and Dave Peticolas on his Poetry Tutorial http://krondo.com/?page_id=1327.  Hopefully when we actually have a ReST framework that doc authors can contribute to, my skepticism will be invalidated though.", "group_id": 292, "id": 186217}, {"user_id": 9229, "stars": [], "topic_id": 7959, "date_created": 1298453934.542443, "message": "@glyph ok, cool :-)", "group_id": 292, "id": 186416}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298454191.8839109, "message": "@jessenoller You mentioned that Twisted needs more narrative documentation, in the style of \"build your own X\" (over in the Async Python topic).  Have you seen http://twistedmatrix.com/documents/current/core/howto/tutorial/index.html or http://twistedmatrix.com/documents/current/core/howto/tap.html or http://twistedmatrix.com/documents/current/core/howto/servers.html or http://twistedmatrix.com/documents/current/names/howto/names.html or http://twistedmatrix.com/documents/current/web/howto/web-in-60/index.html?  Or even perhaps http://krondo.com/?page_id=1327 ?  There are lots of little narrative tutorials about how to do individual things with Twisted; there just isn't one overarching task that can cover everything Twisted can do.", "group_id": 292, "id": 186425}, {"user_id": 5673, "stars": [], "topic_id": 7959, "date_created": 1298488293.528652, "message": "My thought is that the biggest problem isn't the documentation, it's the all-inclusive nature of twisted, which makes it difficult to understand what's what, and how it all fits together.  Documentation could go a long way to alleviate this pain, by clearly outlining the structure of the project, but most of what is called \"twisted\" should really be separate projects built on twisted.  That would make comprehending \"twisted\" a much less daunting task for newcomers.", "group_id": 292, "id": 190025}, {"user_id": 242, "stars": [], "topic_id": 7959, "date_created": 1298491663.79862, "message": "@jcdyer The former required the implementation of complex release infrastructure and in my opinion was a big mistake.  The only place where people seem to not just include all of twisted is a few projects that involve embedded devices.", "group_id": 292, "id": 190510}, {"user_id": 242, "stars": [], "topic_id": 7959, "date_created": 1298491598.2547879, "message": "@jcdyer http://twistedmatrix.com/trac/wiki/TwistedProjects & https://launchpad.net/tx", "group_id": 292, "id": 190502}, {"user_id": 1152, "stars": [], "topic_id": 7959, "date_created": 1298492049.793375, "message": "@glyph I'm never going to say your docs aren't comprehensive; \"unapproachable\" is the term I've most often heard from people trying to figure out what it is. I mean, think about it this way - what would you explain in a PEP getting twisted.core into python core? How would you explain to someone just coming into python what it is?", "group_id": 292, "id": 190577}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298494062.282928, "message": "'pip install twisted' and be happy.", "group_id": 292, "id": 190952}, {"user_id": 1152, "stars": [], "topic_id": 7959, "date_created": 1298491941.926259, "message": "@glyph No, I hadn't - http://krondo.com/?page_id=1327 isn't apparent on the twisted site. I've read the finger tutorial several times. The finger one has always been a stand by, but is dated. JP's web-in-60 was a great start, etc. I know twisted is a lot of things, but finger is something I doubt anyone cares about anymore, and even the ones you linked to (like http://twistedmatrix.com/documents/current/core/howto/servers.html) could stand a little more narrative.", "group_id": 292, "id": 190555}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298493969.710052, "message": "But yeah it hasn't been included in SVN for years.  twisted.web is the way to go.", "group_id": 292, "id": 190933}, {"user_id": 242, "stars": [], "topic_id": 7959, "date_created": 1298493859.0774181, "message": "It is a misconception that web2 was ever \"released\".  Twisted never came prepacked with web2 it was only available from SVN or on platforms where Twisted was \"packaged\" by scooping everything out of SVN and ignoring our prebuilt packages.", "group_id": 292, "id": 190910}, {"user_id": 5673, "stars": [], "topic_id": 7959, "date_created": 1298493753.5539851, "message": "@dreid  Thanks for those links.  IMHO, the fact that Twisted comes prepackaged with a \"Web\" and \"Web 2\" subproject is evidence that too much is included.  I would prefer to see twisted.core distributed on its own and pretty much everything else a pippable package dependent on core.  I know python doesn't handle independent subpackages well, so the others would probably have to become top-level packages.  It may be far too late for such a reorganization, but I do think it would make twisted much more approachable.", "group_id": 292, "id": 190887}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298493941.630204, "message": "I think some of the prebuilt packages actually included web2 by mistake, due to bugs in the aforementioned unfortunately overcomplex release infrastructure.", "group_id": 292, "id": 190927}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298493953.214483, "message": "(Maybe there was even one where it was released on purpose?)", "group_id": 292, "id": 190930}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298494041.267503, "message": "@jcdyer Lots of people say that they want separately installable packages, but we put a great deal of effort into making that a reality, and the only feedback we ever got was about setuptools bugs.  Not a single user ever said \"wow, I'm really glad I could install twisted.names without getting twisted.web\", but dozens and dozens showed up every day for months saying \"why isn't twisted.mail available, I thought I installed twisted\".", "group_id": 292, "id": 190943}, {"user_id": 242, "stars": [], "topic_id": 7959, "date_created": 1298493967.042062, "message": "@jcdyer There are still individual packages http://twistedmatrix.com/trac/wiki/Downloads#IndividualProjectTarballs Not sure what it takes to be \"pipable\" though.", "group_id": 292, "id": 190932}, {"user_id": 6671, "stars": [{"date_created": 1298496139.1633439, "user_id": 214}, {"date_created": 1298496394.252898, "user_id": 242}, {"date_created": 1298500137.1520059, "user_id": 222}], "topic_id": 7959, "date_created": 1298494135.8971429, "message": "I think that people have this (incorrect) feeling that somehow if the package were broken up into smaller distributions, it would be easier to understand or the code would be simpler.  But the code's already factored into separate packages, and if you don't want to read about twisted.news, you can just avoid the 'news' subdirectory.", "group_id": 292, "id": 190966}, {"user_id": 12142, "stars": [{"date_created": 1298607705.7018981, "user_id": 4156}, {"date_created": 1298612190.147948, "user_id": 214}, {"date_created": 1298626361.9848089, "user_id": 13912}, {"date_created": 1298658523.846051, "user_id": 12142}, {"date_created": 1298700282.252142, "user_id": 6671}], "topic_id": 7959, "date_created": 1298601660.7190731, "message": "is there not a big enough market for a big fat book with tons of wit, narrative, history and maybe one ~big, ~comprehensive project that the book shows how to build?  I've got $30 on that.", "group_id": 292, "id": 205206}, {"user_id": 6671, "stars": [], "topic_id": 7959, "date_created": 1298449243.4206121, "message": "@andrewbadr Very few methods are still documented that way (it is no longer our documentation standard; feel free to file bugs to fix specific instances that you find), but, for historical reference, that first-person style of documentation was borrowed from smalltalk.", "group_id": 292, "id": 186220}]