Improve core documentation index page

[itamar]

The core howto documentation is badly organized, and could do with some descriptions and explanations.

[itamarst]

(In [33312]) Branching to 'howto-index-5427'

[itamar]

Ready for review:

 http://buildbot.twistedmatrix.com/builders/documentation/builds/1764

[jesstess]

Thanks for working on this, itamar. Your changes look good; feel free to deploy now if you want, but a few comments:

• "Network programming should be easy... and fun!" It's hard for me to read this with a straight face.
• Is "Test-driven development with Twisted" the third document new users should be reading, after servers and clients? Would the intro to Deferreds be better? Or perhaps TwistedQuotes, which is a short application example then followed by the longer Finger tutorial?
• I'd prefer that the Legacy Documentation not be referenced in the index at all, rather than listed but saying it is broken. We can remove those links and open tickets to either reintroduce updated documentation or remove those documents altogether.

[itamar]

1. Is this a good thing or bad thing? I do want this to be entertaining.
2. I think test-driven development should be pretty central, because that's one of the big wins with Twisted: the ability to test your network code. It's also good marketing for more experienced developers. Moreover, the testing tutorial only adds reactor.callLater to the knowledge from the previous two howtos, and repeats the explanations of factory/protocol etc., so I think it's a reasonable next step.
3. Will do.

Another requirement before resubmitted for review: reorganize book.tex to match the new index.

[itamarst]

(In [33413]) Branching to 'howto-index-5427-2'

[itamar]

OK, I removed two bad howtos, moved telnet howto out of legacy since it can be salvaged (the functionality still exists in non-deprecated form in twisted.conch), updated book.tex (there were *lots* of missing howtos!).

Buildbot documentation slave is happy:  http://buildbot.twistedmatrix.com/builders/documentation/builds/1792

[exarkun]

Thanks. Documentation tickets are super important, we need to keep doing stuff like this.

1. The graphical overview doesn't strike me as particularly useful. Also, it's full of incorrect information. We have another ticket for updating it which people have been avoiding working on for ages. Should we take this opportunity to drop the "document"?
2. It's true that conch provides telnet functionality, but it's not API compatible (at all) with twisted.protocols.telnet, deprecated since Twisted 2.1, which is what the telnet howto documents. We really just need a new howto for the conch telnet library.
3. I am a little bit uneasy about all the new claims of "easy" things in the index. Good documentation shows you that things are easy, it doesn't tell you that they are. +1 on being entertaining, but claiming everything is easy here looks bad to me. It's one of the things that made deferredindepth.xhtml such a terrible document and worthy of deleting here.
4. Here's some scope creep for you. The "low level" section of the index doesn't make a lot of sense to me. SSL, endpoints, and processes are low-level? Not really. SSL and processes are just features you might want, and inasmuch as we're talking about Twisted APIs here, these APIs are probably pretty high-level compared to what a reader is used to, or what they might find elsewhere. And on top of that, endpoints are the highest-level connection setup API Twisted has.

I don't have the tools to build the book on hand. I'll assume you've tested this yourself and it still works and looks proper. Please merge when you've addressed the above points to your satisfaction (unless jesstess has anything to add :). Thanks!

[thijs]

It also looks like there are example listings files that were referenced in the deleted core/howto/deferredindepth.xhtml that can now be deleted.

[thijs]

\input{../specifications/banana.tex} was also removed from the book.tex for some reason.

[itamar]

Review comments have been addressed:

1. Deleted overview and images, added 1712.misc for that ticket, #1712.
2. Deleted telnet.
3. Rewrote the bits about easiness.
4. Renamed that sections to "Networking and Other Event Sources", and moved endpoints to high-level infrastructure.
5. Deleted deferred in depth code listings.
6. I removed banana spec on purpose - it's not on regular howto index, and I doubt people looking at book-like PDF actually want it either.
7. I also made a few more minor edits, e.g. the tutorial section is now "Getting Started".

Buildbot for docs:  http://buildbot.twistedmatrix.com/builders/documentation/builds/1806

[jesstess]

This is a tremendous improvement over the existing index -- thanks for working on this. Please merge!

[itamarst]

(In [33453]) Merge howto-index-5427-2.

Author: itamar Review: jesstess, exarkun, thijs Fixes: #5427, #1712

The core howto index has had many crufty howtos removed, and has been reorganized. Also, the generated PDF should now contain all howtos (it was missing some).